Multi-Input Field

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

Usage

Use the multi-input field if:

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

Do not use the multi-input field if:

  • You want the user to select one entry only. In this case, use the input field or combo box instead.
  • You want the user to select from a pre-defined set of options only. In this case, use the multi-combo box instead.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

Size S

  • Cozy mode.
  • When the user clicks the multi-input field, a new full screen dialog opens. After clicking the input field and typing, the suggestions can be selected. When the user makes a selection, the dialog closes and the token is displayed.
  • The user can review the tokens by swiping them to the left or right.
Suggestions on a smartphone (size S)
Suggestions 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

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

Size L

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

Types

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

Behavior and Interaction

Adding a Token

A token can be added using suggestions or value help. As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. The user can accept the autocompleted value by pressing ENTER. The autocomplete property is set by default if suggestions are available, but can also be switched off.

When an item is selected from the suggestions dropdown, the corresponding token is created, and the input field is ready for the next entry. Tokens are placed next to each other on one line.

Warning
The typeahead input feature is not available for Android devices.
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

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

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

Multi-input field - 'n More' label (desktop)
Multi-input field - 'n More' label (desktop)
Multi-input field - 'n More' label (phone)
Multi-input field - 'n More' label (phone)

If the length of the last selected token exceeds the width of the input field, a label [n] Item/s is shown when the field is not in focus.

Clicking the [n] Item/s label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its delete icon.

If there is only one token in the input field and its length exceeds the width of the input field, the text is truncated. Clicking the token opens a popover below the input field, in which the full text of the token is shown.

Multi-input field - '1 Item' case (desktop)
Multi-input field - '1 Item' case (desktop)
Multi-input field - 'n Items' label (desktop)
Multi-input field - 'n Items' label (desktop)

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

Left/right keyboard cursor
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

Filtering

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

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

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

Multi-input field - Default filtering, autocomplete in the input field is switched off
Multi-input field - Default filtering, autocomplete in the input field is switched off

Copying and Pasting Data from a Spreadsheet or Text File

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

Grouping

You can group the items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

The column headers within the tabular suggestion list remain in place when the list is scrolled (“sticky” behavior).

Multi-input with grouped suggestions
Multi-input with grouped suggestions
Multi-input with grouped tabular suggestions
Multi-input with grouped tabular suggestions

Due to a technical limitation, the group headers are not visible when clicking on the n More text. 

Group headers not shown when clicking on 'n More' items
Group headers not shown when clicking on 'n More' items

Styles

The following images show how the states of the multi-input field are styled.

Unselected
Unselected
Unselected with predefined placeholder
Unselected with predefined placeholder
Unselected on hover
Unselected on hover
In focus
In focus
Selected items shown as tokens
Selected items shown as tokens
Expanded multi-selection
Expanded multi-selection
Error
Error
Warning
Warning
Success
Success
Information
Information

For details on the different states, see UI Element States.

For more information on semantic colors for value states, see How to Use Semantic Colors.

Guidelines

  • Give the control a width that is appropriate for the range of values that are going to be entered. Try to avoid setting a fixed width on this control. Instead, embed it in a proper layout (such as a form, simple form, or grid layout) and work with the layout data property.
  • Provide meaningful labels for all input fields. Do not use the placeholder as a replacement for the label. The placeholder should only provide an additional hint.
  • The multi-input field can currently contain tokens and one free text value. If you allow only validated values, display an error or warning when the user tries to leave the field to indicate that the value entered is invalid, or remove the value.
  • If users try to select an item that has been selected before, we recommend setting an error state and providing a meaningful message.
Multi-input - Error state for an item that has already been selected
Multi-input - Error state for an item that has already been selected
  • You can use the layout options of the form to add the unit of measurement (UoM) after the multi-input control. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.
Developer Hint

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

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

Properties

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

Resources

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

Elements and Controls

Implementation

Input Field

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

Usage

Use the input field if:

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

Do not use the input field if:

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

Responsiveness

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

Note that when tabular suggestions are used, the column headers stay sticky when scrolling within the suggestion list.

Size S (Smartphones)

Cozy mode:

When the user clicks 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
Tabular autocomplete suggestion with sticky header
Tabular autocomplete suggestion with sticky header

Size L (Desktops)

Compact mode:

The full table is shown by 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 implement format validation. If binding is used, validation is carried out by the model, but error handling must still be implemented on the UI side.

Text (default)

Input type text – Keyboard layout on a smartphone
Input type text – Keyboard layout on a smartphone

Number

Input type number – Keyboard layout on a smartphone
Input type number – Keyboard layout on a smartphone

Email

Input type email – Keyboard layout on a smartphone
Input type email – Keyboard layout on a smartphone

URL

Input type URL – Keyboard layout on a smartphone
Input type URL – Keyboard layout on a smartphone

Telephone Number

Input type telephone number – Keyboard layout on a smartphone
Input type telephone number – Keyboard layout on a smartphone

Password

Input type password – Keyboard layout on a smartphone
Input type password – Keyboard layout on a smartphone

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

Examples of input with different number masks
Examples of input with different number masks

Behavior and Interaction

Entering Text Using the Autocomplete Feature

Have a look at the interaction flow below:

Entering Text Using the Value Help Dialog

Have a look at the interaction flow below:

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

Styles

An input field can have the following styles. For more information, see UI Element States.

Input field states
Input field states

Properties

Value State and Value State Message

The input control offers the four value states listed below, for which you can show an additional value state text message when the focus is on the input field.

  1. Error
  2. Warning
  3. Success (no message is available for this state)
  4. Information

For more guidance on when to use which state, see How to Use Semantic Colors.

Input field in semantic colors with message box below
Input field in semantic colors with message box below

Enabled, Read-only and Disabled states

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

  1. Enabled: This is the default setting.
  2. Read-only: The input field isn’t shown, just the value. This is used in display-only forms.
  3. Disabled: The input field is shown with a visual indication that editing isn’t possible (for example, because the user isn’t authorized to make changes).
Input Field - Enabled
Input Field - Enabled
Input Field - Read only
Input Field - Read only
Input Field - Disabled
Input Field - Disabled

Required

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

Required input field
Required input field

Maximum Length

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

Placeholder

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

Placeholder
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. Instead of defining a fixed width, we recommend 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.

Text Alignment

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

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

Value Help

To help the user find the correct value, you can enable the value help option (propertyshowValueHelp). 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). 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.

Input Field with value help
Input Field with value help
Value help only
Value help only

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

Input Assistance

Intelligent systems can help users by recommending appropriate content or suggesting an action or input the user may “prefer”. The system assists the user by entering data or filtering data. Typical examples might be a search phrase suggestion, an appropriate form template, or a set of suggested default values for certain fields, based on the user input and interaction history.

For more information, see Designing Intelligent Systems – Input Assistance.

Autocomplete Suggestions

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

As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. The user can accept the autocompleted value by pressing ENTER. The autocomplete property is set by default if suggestions are available, but can also be switched off.

Warning
The typeahead input feature is not available on Android devices

Single Value with Autocomplete

Single-value autocomplete displays a list of suggestions with one left-aligned value. As a base for the aggregation suggestionItemssap.ui.core.Item is used.

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

See this 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 a customer and an ID.  As a base for the aggregation of suggestionItemssap.ui.core.ListItem is used.

The text property is displayed first, and is left-aligned. The additionalText property is right-aligned. The first text property is autocompleted in the input field.

Use the two-value autocomplete feature if you want to search by two attributes. This ensures that the search is carried out for both attributes.

See this 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. Use the tabular autocomplete feature if you need to display more than two attributes.

For input fields in a tabular view, we recommend using a maximum of 4 columns. Focus on columns that are really relevant for the use case.

To use the tabular autocomplete feature, use the suggestionColumns aggregation to define the columns and the correct responsive behavior for the pop-in. Define appropriate responsive behavior for sizes S and M. 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:

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.

The column headers remain in place when the user scrolls through the suggestion list (“sticky” behavior).

See a live example of tabular autocomplete suggestions.

Tabular autocomplete
Tabular autocomplete

Grouping

You can group the items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

Input with grouped suggestions
Input with grouped suggestions
Input with grouped tabular suggestions
Input with grouped tabular suggestions

Guidelines

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

Maximum Columns

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

Maximum Length

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

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

Placeholder

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

Description

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

Width

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

Editable and Enabled States

Editable

Property settings: editable = true, enabled = true

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

Not Editable

Property settings: editable = false, enabled = true

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

Disabled

Property settings: editable = not relevant, enabled = false

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

Text Align

Align left if:

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

Align right if:

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

Value Help

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

Use this option in combination with the autocomplete suggestion feature.

When the user clicks 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.

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 fieldcombo boxmulti-combo box, and select controls.

Input field – New action
Input field – New action
Input field – Edit action
Input field – Edit action

Resources

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

Elements and Controls

Implementation

Dialog

The dialog control (sap.m.Dialog) interrupts the current app process to prompt the user for information or for a response. It forces a decision or a confirmation that needs to be signed off by the user.

Usage

Use the dialog if:

  • You want to display complex content (that is not a floorplan), but don’t want the user to navigate away from the current page.
  • You want to display an additional step or process that needs to be confirmed by a user action.
  • You want to enable the user to create an object with a small number of fields (up to 8 fields).

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.
  • You want to enable users to create an object with more than 8 fields. Use an object page instead.
  • You want to display a floorplan. Floorplans are not meant to be displayed inside a dialog.

Responsiveness

The dialog provides different behavior on a smartphone than on a tablet or desktop. We distinguish between “cozy” and “compact” dialogs. For more information, see content density.

The buttons in the toolbar are aligned differently on the various devices. On a smartphone, they extend across the entire footer toolbar, but on a tablet or desktop device, they are right-aligned.

Size S (Smartphone)

Full Screen Dialog

We recommend displaying dialogs in S size in full screen mode to help users focus on the content of the dialog (property stretch = “true”). The toolbar containing the actions is positioned at the bottom of the dialog.

Position of the Action Buttons

On smartphones, a dialog can have one or two actions, which are located in the footer and right-aligned.

Full screen dialog - Size S
Full screen dialog - Size S

When to Open Full Screen or Modal

Always display message dialogs 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, open them in full screen mode to help the user can focus on the content of the message. The dialog control offers 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

You can let users navigate to another page within the dialog. On the second page, an arrow at the top of the dialog allows users to navigate back to the first page.

Navigation pattern list - Size L
Navigation pattern list - Size L
Navigation pattern details - Size L
Navigation pattern details - Size L

 

Resizable

You can let users change the size of the dialog (property resizable = “true). The resizable indicator then shows in the bottom-right corner of the dialog.

Resizable indicator in the bottom right-hand corner - Size L
Resizable indicator in the bottom right-hand corner - Size L

Draggable

By clicking and holding on the heading, users can drag the dialog to another position (property draggable = “true”).

Dialog can be moved by dragging the title - Size L
Dialog can be moved by dragging the title - Size L

 

Messaging Within a Dialog

Do not show message popovers within dialogs. Use highlighting to show issues with content fields. For more information, see form field validation.

 

Editing and Saving Content

If a dialog is used for editing, keep it simple. If you need more than 8 editable fields, consider other solutions instead, such as navigation to a detail page.

The data in the dialog is only saved when the user clicks Create or Save. Use form field validation within the dialog to make users aware of any errors.

The data in the dialog is lost if the page is refreshed during the editing process (also in the draft scenario), or if the user chooses Cancel.

Highlighted form fields in a dialog - Size S
Highlighted form fields in a dialog - Size S

 

Types

Standard Dialog

Use the standard dialog unless you need one of the specialized dialogs below. The standard dialog has a header with a grey background, and no icon.

Message Box

The message box is a special type of dialog that is used to display messages quickly. For each type of message, you 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 (optional): Subheaders appear below the main header. Since 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 (optional). If no buttons are defined, the default Close button is shown.

Example of a dialog structure (Cozy)
Example of a dialog structure (Cozy)

Emphasized Buttons in a Dialog

Always use an emphasized button for the the standard action. Emphasizing the main action in the dialog toolbar helps users to focus on the most likely choice. This saves users time and gives new users a sense of orientation.

Never use an emphasized button for Cancel.

Emphasized button in the dialog footer
Emphasized button in the dialog footer

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

 

 

 

 

 

 

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 for a master-detail scenario using the flexible column layout, as well as in popovers or dialogs. For certain use cases, lists can also be used in the dynamic page layout.

Usage

Use the list if:

  • You want to display a homogeneous set of basic data.
  • You need to sort, group, or filter simple datasets.
  • 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 datasets that need to be extensively sorted, grouped, filtered, or edited. In this case, use a table.
  • You work with complex hierarchies. In this case, 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, since they are usually used to navigate to the item details. For custom list items, you can also wrap the texts, 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 the preferable method for 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

Avoid empty lists. If necessary, provide instructions on how to fill the list with data (sap.m.List/ sap.m.ListBase, properties: noDataText, showNoData).

Examples:

  • If a list is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the list with data.
  • If a list is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    No filters set. To start, enter your search and filter settings and run the search.
  • If a list is used together with a filter bar and the filter does not return results, use the following text:
    No items found. Check the search and filter settings.

Adapt the texts above if:

  • The standard text is not precise enough for your use case (for example, no search is offered, only the search is offered).
  • You are using the live search (no Go button in the filter bar). In this case, leave out “run the search”.
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).
Empty list
Empty list

Count

List items can have a count, which is located on the far right of a row. You can use the count in simple lists, such as those that contain standard list items, to indicate how many subitems the user can expect when navigating to 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

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

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted items using status colors
Highlighted items using status colors
Highlighted items using indication colors
Highlighted items using indication colors

Behavior and Interaction

There are several ways to interact with the list and its list items:

List Level

Scroll

The height of the list is defined by the number of items it contains. It does not have its own scroll container, but is scrolled together with the app.

If the list 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 triggered by scrolling (preferred), or by clicking the More button.

When the user scrolls, the title and the filter infobar can stick to the top of the surrounding layout container (sap.m.List, property: sticky).

Information
The “sticky” feature comes with some limitations:

  • It is not available on all browsers. In non-supporting browsers, the corresponding areas are not fixed on top of the surrounding layout container while scrolling.
  • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the list is placed within the object page.
  • If the focus is set to a sticky area, the list is automatically scrolled to top.

Sticky title
Sticky title

Mode

The list can have several modes. The respective property (Mode) allows the following selection methods:

  • None
  • SingleSelectMaster (used to pick one item with no additional indicator, as in the master list for a master-detail scenario with the flexible column layout)
  • 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). The Shift key can be used to select a range.
  • Delete (used to delete items from the list using a delete indicator on the far right)
Developer Hint
In multiple selection mode, users can (de)select all items using the shortcut Ctrl+A. This only affects items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded (for example, items added via lazy loading with growingScrollToLoad). This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

To process all items, listen to the selectionChange event and to its flag selectAll. This indicates whether Ctrl+A was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

List with explicit single selection
List with explicit single selection
List with multiple selection
List with multiple 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

Line Item Level

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 pencil appears on the far right, indicating that something can be changed. The user can only click the pencil.)
  • Detail and active (same as “detail”, but the item itself is also clickable)

The example shows how all these types are visualized.

All list item types: inactive, detail, navigation, active, detail and active
All list item types: inactive, detail, navigation, active, detail and active

Indicate Navigated Item

When multi-selection is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case only (multi-selection list with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.ListItemBase, property: navigated).

Navigated item
Navigated item

Swipe

You can provide a swipe feature (sap.m.List, properties: swipeDirection, swipeContent) for approving or deleting items quickly without having to look at the details. Swiping is possible in both directions (left to right / right to left). You can provide different actions for each direction. Because swiping is only available on touch devices, only offer it as an additional feature. Swiping should never be the only way to perform the action.

List with swipe action
List with swipe action

Context Menu

The context menu can be triggered for the list or per item.

It gives users an alternative way of modifying the focused elements by giving access to context-specific functions.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or Shift+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

List - context menu
List - context menu

Drag and Drop

One or several items can be repositioned within a list or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop
Whole item as drop target
Whole item as drop target

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 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 without separators
List without separators

Guidelines

Text Length

When you use the list in the first column of the flexible column layout, keep the texts as short as possible and only as long as necessary. If you expect large numbers, use formatting instead.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the list. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning
The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

  • The number of rows in the table
  • The number of displayed columns
  • The complexity of the cell content (for example, simple text vs. complex charts)
  • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
  • The browser being used

Custom List Items

If none of the list items provided suits the requirements of your app, you can also create a custom list. If you choose this option, ensure that your custom list item is responsive when resized.

When creating custom list items, take the following guidelines into account, as needed:

Radio Button

Only use radio buttons if they are absolutely necessary. One example would be if you want to distinguish single selection from navigation. This is a rare case in which visible radio buttons for single selection are allowed.

Actions

To trigger actions on single items, show the actions on a toolbar above the list. Do not offer actions on multiple items if the list is expected to have fewer than 10 items in most cases.

The following actions on single items must always be inline:

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

You can combine delete and edit actions, or delete and navigation actions. However, edit and navigation actions cannot be combined.

To trigger actions that are independent of the selection, show the actions on a toolbar above the list. For example: AddCollapse AllExpand 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). When clicked, active items trigger an event that can be handled by the app (for example, to open a dialog). Selection of items and expanding/collapsing a node do not trigger the event, and are handled by the tree. Do not use the active item type 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 the single selection master.

Add Items

For adding items, place an Add or Create text button on the table toolbar.

  • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
  • Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the table, with a visual highlight at the beginning of the row.

Enable the shortcut Ctrl+Enter to trigger the Add and Create buttons.

For more information, see the guidelines for managing objects (including subarticles).

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Let users choose whether to apply the action anyway or cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element – States.

If the action was applied and the items are still available, keep them selected.

Message for action which applies to a part of a selection
Message for action which applies to a part of a selection

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, it is not accessible, since there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.

Use drag and drop only in addition to existing visible UI elements
Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within the list, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop targets in between items
Drop targets in between items

Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on values, the dropped item needs to take on the corresponding value of the target group. If this is not wanted, do not allow users to rearrange items in grouped lists.

 

Example:

A list is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Don't
Do not combine rearranging items with grouping, unless you know exactly what you're doing
Do not combine rearranging items with grouping, unless you know exactly what you're doing

Export to Spreadsheet

Apps can provide a menu button for exporting list data to a spreadsheet (for example, on the relevant toolbar). For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button
'Export to Spreadsheet' menu button

Resources

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

Elements and Controls

Implementation

Grid List

As with the list and the responsive table, the grid list displays a set of items. In contrast to both controls, the grid list displays the items not in rows, but in a grid.

The grid list is usually used as an alternative view for a list or table. It is ideal for displaying images, charts, object cards, and other content, which profit from more height (but less width).

Grid List
Grid List

Usage

Use the grid list if:

  • Your content is “visual” and profits from the rectangular format of the items. This is true for e.g. images, charts, and object cards.
  • The focus is on items, not on cells. The grid list shows complete items.
  • You want to display a homogeneous set of basic data.
  • You need to sort, group, or filter simple data sets.
  • As an alternative view for tables or lists, if the content profits from the different format.

Do not use the grid list if:

  • Your content is not appropriate for a card-like format. For example, do not use the grid list for displaying a wall of text. Use a table instead.
  • 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.
  • Data needs to be structured in a hierarchical manner. In this case, a tree might be more appropriate.
  • 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 the CSSGrid.
  • You want to manage complex datasets that need to be extensively sorted, grouped, filtered, or edited. In this case, use a table.

Responsiveness

The responsiveness of the grid list results from the underlying grid. The underlying grid is defined by rows and columns. Columns can have a minimum and maximum or a fixed size. Whenever an additional column fits on the screen, it will be added. If a column does not fit on the screen anymore, it will be removed. Items are re-layouted accordingly.

Optionally, there can be different configurations for the underlying grid based on breakpoints, for example based on the device types.

To define the grid layout and behavior, you can use one of the pre-defined layouts:

  • Grid box layout: Adds a variable number of columns depending on the available screen width. Columns have either a fixed width or can “breathe” slightly. All rows have the same height, and all items are the same size.
  • Responsive column layout: The number of columns depends on breakpoints (4 columns for size S, 8 for size M, 12 for size L, and 16 for size XL). The width of the columns grows or shrinks with the available screen space until the next breakpoint is reached. The row height of the grid is determined by the height of the highest item in the row. The number of rows and columns taken up by an item can differ.

Alternatively, you can define your own grid. This gives you much greater flexibility to influence both the layout and the (responsive) behavior of the grid.

The underlying grid defines the available space per item. The width can differ pending on the screen width (“breathing”) or be fixed. The height can differ pending on the content of the item or be fixed. “Breathing” items make better use of the available screen space and is therefore recommended. Make sure, that the item adapts to the resulting width / height, for example by

  • Re-layouting the item content
  • Hiding less important information
  • Re-sizing content, such as images or charts.

Items can use one ore more grid cells. Items can also be different sizes (for example, to allow for varying text lengths/wrapping in different items).

Size S
Size S
Size M
Size M
Size L
Size L

Components

  • The title bar holds the title and, an item counter. Instead of a title bar you can use a toolbar, including title, counter, variant management and actions.
  • Optionally, a filter infobar should appear when the grid list is filtered and shows information on the filter settings.
  • The collection of grid list items, layouted on a grid, occupies the main part of the grid list.
  • 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. Use More only, if content is shown below the grid list.
  • The footer can contain additional static text information.
Schematic visualization of the grid list
Schematic visualization of the grid list

Title Bar

The title bar contains the title of the grid list and an item counter

Title Bar
Title Bar

Instead of the title bar, a toolbar can be used instead. If done so, use a title control to display the title and item count. Variant management and actions can be added in this case. The toolbar can contain entry points for the view settings dialog, as well as view switches in the form of a segmented button, and buttons for actions like for example Add, or Edit.

Toolbar instead of title bar
Toolbar instead of title bar

For the title, keep the following in mind:

  • Use a title if you need the item count, toolbar actions, or variant management. To avoid repeating text, feel free to use generic text as a title, such as Items.
  • Do not show the title bar at all, if all elements (title, item count, variant management, toolbar) are available in the surrounding area.
    Example: An object page (sub-)section contains only one grid list. In this case, add the item count and the toolbar to the (sub-)section header.
Developer Hint
Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table. If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

For displaying the item count, use the following format:

[title text] ([count])

for example:

Items (2,534)

For the item count, keep the following in mind:

  • include all the items that a user can reach by scrolling except group headers.
  • Remove the item count if there are zero items.
  • Do not show a count on the title bar, if a More button is used. Show the count on the more button instead.

If possible, keep the title bar sticky (sap.m.GridList, property: sticky).

Filter Infobar

Beneath the toolbar, display a filter infobar (which itself is a special toolbar) if the grid list is filtered.

Filter infobar
Filter infobar

Items

The items (sap.f.GridListItem) are placed on a grid. To specify the design of items, it is recommend (but not mandatory) to follow the guidelines for object cards. Be aware that the item itself is responsible for its own responsiveness.

Use the grid list only, if your content profits from the format. This can apply to images, charts, but also to object cards or quick views. Another option is to mimick the format (but not the visual) of existing objects (e.g. business cards).

A grid list item can contain any content. This includes single controls, or a combination of controls (e.g. by using layout containers).

When designing an item,

  • Use the grid list item as starting point and make sure that the content adapts responsively to a changing item width / height.
  • Although the grid list can technically work with other list items (e.g. the standard list item), do not use them. They are not responsive enough for being used in a grid. In addition, selectors, navigation indicators and other elements are layouted differently (optimized for the list, not for the grid list).
  • Take care that an item can be identified, e.g. by adding a title, and if needed a sub title.
  • To show a string with an ID as identifier, use the title for the string, and the subtitle for the ID.
  • For status information, use semantic colors on foreground elements.
  • Avoid truncation. Use controls that wrap the text and configure them accordingly.
  • If an edit mode is needed, change your text controls (labels, text, and links) to input fields or other appropriate editable 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 item.

Not all items have to follow the same structure. This could be the case if one item is locked, but another item is in edit mode. Another example is to show a set of objects of different types in the same grid list.

Example for a grid list item
Example for a grid list item
Another example for a grid list item
Another example for a grid list item

Highlight

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

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry- / process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users what exactly is wrong. Make sure that you provide this information within the item, ideally in the same color.

For details on the usage of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted item
Highlighted item

States

To show that an item is unread, use the corresponding flag (sap.m.GridList, property: showUnread, sap.f.GridListItem, property: unread). This shows most of the content in bold font.

Unread item next to a read item
Unread item next to a read item

To show that an item has been modified, for example, within the global edit flow, add the string (Modified) near the item identifier.

A modified item
A modified item

To show that a modified item contains an error (for example, within the global edit flow), add the string (Contains errors) near the item identifier. To do this, use an object status control with the error state (sap.m.ObjectStatus, property: state, value: sap.ui.core.ValueState.Error). In addition, highlight the item accordingly (sap.f.GridListItem, property: highlight).

An item with an error
An item with an error

To show that an item is locked, use a transparent button with the corresponding icon and the text Locked by [Name] near the item identifier. The user can click 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 near the item identifier. The user can click the button to open a popover showing the timestamp of the last change.

An item with draft state
An item with draft state

Show only one state at any one time.

“More” Button

The More button loads more items to the front end if not all items have yet been loaded.

"More" button

Footer

The footer can be used to display additional static information relating to the content.

Grid list footer
Grid list footer

Behavior and Interaction

Scroll

The height of the grid list is defined by the number of items it contains. It does not have a scroll container on its own but is scrolled together with the page. When the user scrolls the page, the title bar and filter infobar can stick to the top of the surrounding layout container (sap.m.GridList, property: sticky).

Information
The “sticky” feature comes with some limitations:

  • It is not available on all browsers. In non-supporting browsers, the corresponding areas (title bar, filter infobar) are not fixed on top of the surrounding layout container while scrolling.
  • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the grid list is placed within the object page.
  • If focus is set to a fixed column header, the grid list is automatically scrolled to top.

Sticky toolbar
Sticky toolbar

Showing more items

If the grid list works in a “growing” mode, it only loads a few items at first. Additional items are only loaded (and rendered) on request. This request can either be triggered by scrolling (preferred), or by clicking the More button. Use the latter one only if content follows below the grid list. Use the “growing mode”, if more than 200 items are expected to be displayed.

If using the “More” button,

  • show the number of items already loaded and (if possible) the total number items below the text More.
  • do not show an item count on the title bar. Use the count on the More button instead.

In any case, if the “growing mode” is used, do not show more than 1,000 items overall.

Select

A grid list can have one of the following selection modes (sap.m.GridList/ sap.m.ListBase, property: mode):

  • None: Items cannot be selected (sap.m.ListMode.None).
    Beware: Items can still use the sap.m.ListType “navigation”, which allows click handling on specific items. Only use this option if the click triggers navigation to a corresponding item details page.
  • Single selection master: One item in the grid list can be selected. Items are selected by clicking the whole row. The single select master mode has no obvious visual cues, such as checkboxes or radio buttons. It only provides a light blue background for the selected state. Because of this, it can barely be differentiated from grid lists without selection (mode: None). Single select master is the preferred mode for single selection. (sap.m.ListMode.SingleSelectMaster).
Selected item in
Selected item in "single selection master"
  • Single selection left: One item in the grid list can be selected. For this, the grid list provides radio buttons on the left side of each item. Only use this mode if a click on the whole item is being used for something else, such as navigation. (sap.m.ListMode.SingleSelectLeft). Even in this case, prefer single select master and synchronize the selection with the navigation, so that the navigated item is also the selected item.
  • Multi selection: Users can select one or more items. For this, the grid list provides checkboxes on the left side of each item. (sap.m.ListMode.MultiSelect). The Shift key can be used to select a range. Try to avoid combining multi selection with navigation.
An unselected and a selected item in
An unselected and a selected item in "multi selection"

For all single selection modes, make sure that one item is initially selected. Otherwise, the user cannot return to the initial state. A selected item can only be deselected by selecting another item.

Click an Item

The whole item can be clickable. An event is fired by clicking the item (anywhere where there is no interactive control inside the item). Apps can react on the event, for example, by opening a dialog (sap.f.GridListItem, 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 grid list in “single select master” mode.

Drag and Drop

One or several items can be repositioned within a grid list or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

When using drag and drop, keep the following in mind:

  • Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, it is not accessible, since there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.
  • If you offer drag and drop for rearranging items within the grid list, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).
  • Be aware that due to the re-arrangement of the items which happens after an item is dropped, it is not always clear where the item will finally be placed.
  • When dropping items from outside the grid list, adapt the size of the drop indicator to match the target layout of the item (sap.f.dnd.GridDropInfo, property: dropIndicatorSize).
  • Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.
  • When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on a specific data point, the dropped item needs to take on the value of the target group for the corresponding data point. If this is not wanted, do not allow users to rearrange items in grouped grid lists. Example:
    A grid list is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Loading Data

To indicate that the grid list is currently loading items, use the busy state. (sap.m.GridList, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Empty Grid Lists

Try not to display an empty grid list. If there is no way around this, provide instructions on how to fill the grid list with data (sap.m.ListBase, properties: showNoData, noDataText).

Examples:

  • If a grid list is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the grid list with data.
  • If a grid list is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    To start, set the relevant filters.
  • If a grid list is used together with a filter bar and the filter does not return results, use the following text:
    No data found. Try adjusting the filter settings.

Adapt the texts above if:

  • The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of filter settings).

Context Menu

You can attach a context menu to a grid list. The context menu gives users an alternative way to modify the whole grid list or an individual item by providing access to context-specific actions. A context menu is opened by right-clicking (mouse), long press (touch devices), or via keyboard using the context menu key or Shift+F10. If a control inside a grid list is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar). Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

Be aware that using the context menu overrides the browsers context menu, which can no longer be opened.

Group

If grouped, a group header is displayed (sap.m.GroupHeaderListItem) above all items which belong to the corresponding group. The group header is not interactive.

A grouped grid list
A grouped grid list

Guidelines

Actions

To trigger actions on multiple items, use a multi-selection grid list (sap.m.GridList, property: mode, value: sap.m.ListMode.MultiSelect), and offer the corresponding actions on the toolbar of the grid list. Keep the toolbar sticky (sap.m.GridList, property: sticky).

In rare cases, you can also offer the corresponding actions in the footer toolbar. Do this only if the grid list is the only area on the screen to which actions can be applied and if the actions are finalizing.

Do not offer actions for multiple items if the grid list is expected to have fewer than 10 items in most cases.

To trigger actions on a single item only (sap.m.GridList, property: mode, value: sap.m.ListMode.SingleSelectMaster), the action can also be shown within the item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every item 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. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

The following actions on single items must always be in-line:

  • Delete: Use the “Delete” mode of the grid list (sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This places a Delete button at the right side of an item. Clicking 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 grid list and therefore cannot be used together with single selection or multi-selection.
Delete button
Delete button
  • Navigation: Use the “Navigation” item type (sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This places a Navigation indicator at the right side of an item and the entire item becomes clickable. Use this to navigate to a new page containing item details. In rare cases, you can also use this for the category navigation pattern without navigating to another page. By contrast, clicking an interactive control within an item does not trigger the navigation event. Instead, the corresponding control handles the click event.
    “Navigation” is an 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: Use the “Detail” list item type (sap.f.GridListItem, property: type, value: sap.m.ListType.Detail). This places an Edit icon at the right side of an item. Clicking the button triggers the edit event. Use this event to switch the corresponding 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

From these three actions (delete, navigation, and edit), you can combine delete and edit, or delete and navigation. Edit and navigation cannot be combined.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the responsive table. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning
The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

  • The number of rows in the table
  • The number of displayed columns
  • The complexity of the cell content (for example, simple text vs. complex charts)
  • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
  • The browser being used

Add Items

  • Place the Add or Create text button on the toolbar of the grid list.
    • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
    • Use Add if the item already exists and is merely added or assigned to the current object.
  • Place new items always as the first item of the grid list.
  • Use highlight (information state) on the new item.
  • Enable the shortcut Ctrl+Enter to trigger the Add and Create buttons.

There are three possibilities for adding an item, which should be considered in the following priority:

  • Add the item inline. Create an empty, editable item as the first item of the grid list. Show the Save button on the toolbar of the grid list. This option is recommended for simple scenarios where just a few input fields have to be filled.
  • Open a dialog for items where up to 8 input fields need to be filled. Save the new item at the dialog level.
  • Navigate to a new page. This behavior should only be used for very complex scenarios that cannot be handled by a dialog (for example, creating complex objects). When the user presses Save in the footer toolbar of the create page, navigate back to the grid list.

There are three different states of a new item:

  • New: The item was just created and is still in edit mode. It is highlighted with a visual indicator (information state).
  • Recent: The item was saved but is still highlighted and displayed as the first item of the grid list. Current filter, sort and group criteria are ignored since the item should remain visible.
  • As soon as the grid list is sorted, filtered, or grouped again, the new item is handled accordingly and loses the visual highlight, but not before.

In the context of the draft handling new items are not saved on grid list level, but rather with the entire draft.

Export to Spreadsheet

Mass Editing

  • Provide multiselection (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.

For details, see mass editing.

Paste

To paste data from the clipboard to the grid list, the browser functionality for paste can be used (Ctrl+V or browser context menu).

If the focus is on item level, the app has to take the data from the clipboard and add it to the corresponding controls within the items.

If the focus is on an editable control within an item, the control gets the data automatically.

Pasting via context menu does not work if a custom context menu is used.

View Settings

  • Provide individual buttons for each of the following settings on the toolbar of the grid list: sort, filter, group.
  • Clicking one of these buttons opens the view settings dialog or P13nDialog dialog with just the relevant page inside.
  • When closed, apply the settings to the grid list accordingly.

Keep the following in mind:

  • Do not offer any of these features if the grid list 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 on the toolbar of the grid list. Use the filter bar instead.
  • Always use only the view settings which are really needed. For example, do not offer grouping if it does not support your use case well.
  • Persist the view settings. When a user reopens the app, show the grid list with the same sort, filter, and group settings as last defined by this user.

Sort

  • For the default sort settings, sort by the item title, which is usually the identifier of an item.
  • If you offer sorting, offer it for each data point available in the item. Allow sorting in both directions, ascending and descending. The descending sort order must always be the exact reverse of the ascending sort order.
  • For each data point, provide a meaningful sort order. For example:
    • Sort text alphabetically
    • Sort numbers by their value
    • Sort status information by the severity of the status:
      • Ascending: Sort status information from positive to negative, with neutral last.
      • Descending: Sort status information from negative to positive, with neutral first.
      • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
      • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Filter

  • To display the current filter state, use the infobar below the title. Clicking the infobar opens the filter page of the corresponding dialog.
  • Show the infobar only if the filter settings are not shown somewhere else. For example, do not show the infobar for settings taken in the filter bar or in a select placed in the toolbar of the grid list.
  • If the infobar is shown, provide an option to reset all corresponding filters on the infobar.
  • Keep the infobar sticky (sap.m.GridList, property: sticky).
Guidelines
To display the current filter settings on the infobar, consider using the list formatter (sap.ui.core.format.ListFormat).

Group

  • 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 data point]: [Grouping Value]
  • If there is no grouping value, show the following text:
    [Label of the grouped data point]: (Not Available)
    This is the case if you have a group of items that don’t have a value for the grouped data point.

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection,

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action, if it can be applied to all selected items.
  • Enable the action, if it can be applied to a part of the selected items. If the action is triggered, show a message that informs the user about how many items will be affected. Provide the choice to apply the action anyway or to cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element States.

If the action was applied, and if the items are still available, keep them selected.

Message for action which applies to a part of a selection
Message for action which applies to a part of a selection

To trigger actions that are independent of the selection, show the actions on the toolbar of the grid list. Examples of such actions are add, edit (in the sense of changing the whole table to edit mode), sort, filter, and group.

To trigger a default action on the whole item, use the “Active” or “DetailAndActive” list item type (sap.f.GridListItem, 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 Active 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.

Grid Lists in Object Pages

A grid list with up to 20 expected items can be displayed right away, without lazy loading.

If you expect the grid list to have more than 20 items, use one of the following 3 options:

  • Lazy loading (More button): Use this option if you expect to have up to 100 items.
  • Tab navigation: If you expect to have more than 50 to 100 items, but less than 400, use the object page with tab navigation instead of anchor navigation. Put the grid list on a dedicated tab.
  • Navigation to a list report: If you expect the grid list to have more than 400 items, or if the tab approach is unsuitable, restrict the number of items in the grid list itself to a reasonable amount. To provide the user with a way to work with the entire grid list, offer navigation to a separate list report containing all items.

For all of the three options mentioned above, we recommend providing a search, and if feasible, sort and filter capabilities for the grid list in the object page. Grouping should be avoided.

For more information on the use of grid lists within the object page, see Object Page – Tables.

Properties

sap.f.GridList

The following additional properties are available for the grid list:

  • The property: inset adds a margin on all sides of the grid list.
  • The property: headerText is a simple way to set the title for the grid list. However, this excludes the following:
    • A separate toolbar
    • variantManagement
  • 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 grid list.
  • The property: includeItemInSelection uses a click on the whole item to select the corresponding item if the grid list is in a selection mode. This competes with other settings like “Navigation” or “Active” and should therefore not be used in combination with these two settings.
  • 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 grid list is set to busy state)
  • The property: modeAnimationOn does not have any effect. Do not use it.
  • The property: showSeparators does not have any effect. Do not use this property.
  • The property: swipeDirection does not have any effect. Do not use this property.
  • The property: rememberSelections leaves items selected even if they are currently not 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 grid list to a busy state. While in busy state, the whole grid list 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 grid list has been set to this state. Use the default value.
  • The property: visible shows the grid list (“true”) or hides it (“false”).
  • The property: tooltip provides a tooltip for the whole grid list. Do not use it.

sap.f.GridListItem

The following additional properties are available for sap.m.ColumnListItem:

  • The property: selected allows an item to be selected programmatically.
  • The property: counter shows a number on the right side of an item. This is used in cases like showing the number of subitems.
  • 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 item. 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

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 for a master-detail scenario using the flexible column layout and in popovers or dialogs. In certain use cases, they can also be used in the dynamic page layout.

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 first column of the flexible column layout).
  • Selecting one or more items out of a set of hierarchically structured items is a main use case.
  • The hierarchy has a restricted number of levels (up to about 12, depending on the content) 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 very 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 around 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 wrap to ensure that the tree adapts to the new size.

In addition, the tree changes the indentation per level dynamically when the user expands a node, based on number of levels currently showing.

Tree displaying 2 levels
Tree displaying 2 levels
Tree displaying 3 levels
Tree displaying 3 levels
Tree displaying 4 levels
Tree displaying 4 levels

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)
  • text
  • A counter (optional)
  • Additional buttons with actions such as Edit, Navigate, or Delete (optional)

If additional controls are needed, use a custom tree item. The custom tree item allows you to use any combination of controls inside the tree.

Standard tree item
Standard tree item

Behavior and Interaction (incl. Gestures)

Tree Level

Scrolling

The height of the tree is defined by the number of items it contains. It does not have its own scroll container, but is scrolled together with the app.

Same tree, with different expand state
Same tree, with different expand state

When the user scrolls, the title and the filter infobar can stick to the top of the surrounding layout container (sap.m.Tree, property: sticky).

Information
The “sticky” feature comes with some limitations:

  • It is not available on all browsers. In non-supporting browsers, the corresponding areas are not fixed on top of the surrounding layout container while scrolling.
  • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the table is placed within the object page.
  • If focus is set to a sticky area, the tree is automatically scrolled to top.

Sticky title
Sticky title

Selection Modes

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, for example navigation.
Single selection with radio buttons. Use only if row clicks are used for something else, for example navigation.

Multiple selection: 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 of the others. The Shift key can be used to select a range (sap.m.ListMode.MultiSelect).

Developer Hint
In multiple selection mode, users can (de)select all items using the shortcut Ctrl+A. This only affects items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded (for example, items added via lazy loading with growingScrollToLoad). This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

Also note that Ctrl+A only (de)selects items within expanded nodes.

To process all items, listen to the selectionChange event and to its flag selectAll. This indicates whether Ctrl+A was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

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

Line Item Level

Expandable and Collapsible Nodes

An Expand/Collapse button is provided automatically for each node.

Expand/collapse button
Expand/collapse button

Highlight an Item

To highlight an item, use the “highlight” indicator (sap.m.TreeItemBase, properties: highlight).

Highlighted item
Highlighted item

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 the line triggers the navigation event. However, clicking 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

Indicate Navigated Item

When multi-selection is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case only (multi-selection tree with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.TreeItemBase, property: navigated).

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

Context Menu

You can attach a context menu (sap.m.Menu) to a tree. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

The context menu can be triggered for the tree or per item.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or Shift+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a tree is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Tree - Context menu
Tree - Context menu

Drag and Drop

One or several items can be repositioned within a tree or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop
Whole item as drop target
Whole item as drop target

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.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the tree. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning
The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

  • The number of rows in the table
  • The number of displayed columns
  • The complexity of the cell content (for example, simple text vs. complex charts)
  • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
  • The browser being used

Title

Use a title only if the title of the tree is not indicated in the surrounding area. If needed, implement the title text by adding a title to a toolbar. Place the toolbar above the tree.

Do not use a title if it simply repeats text that is already above the tree. For example:

  • Beverages tree is the only control on a tab labeled Beverages.
  • A section or subsection on an object page contains only one tree.

Use a title if you need the item count, toolbar, or variant management. To avoid repeating text, feel free to use generic text as a title, such as Items.
Exception: If the surrounding area contains the title, and both the item count and toolbar can be added to the surrounding area, no additional title is needed.
Example: An object page (sub-)section contains only one tree. In this case, add the item count and the table toolbar to the (sub-)section header.

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 only leaves (for example, if nodes are mainly used for categorization).

Remove the item count in the title if there are zero items.

If possible, keep the toolbar sticky (sap.m.Tree, property: sticky).

Developer Hint
Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the tree.

If you don’t use a title (for example, to avoid repetition), make sure that the tree is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

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

 

Examples:

  • If a tree is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the tree with data.
  • If a tree is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    No filters set. To start, enter your search and filter settings and run the search.
  • If a tree is used together with a filter bar and the filter does not return results, use the following text:
    No items found. Check the search and filter settings.

Adapt the texts above if:

  • The text is not precise enough for your use case (for example, no search is offered, only the search is offered).
  • You are using the live search (no Go button in the filter bar). In this case, leave out “run the search”.
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).
Provide meaningful instructions within an empty tree
Provide meaningful instructions within an empty tree

Highlighting Items

To show that an item needs attention, you can display a highlight indicator in front of the item. The highlight indicator can be used to indicate:

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors.

(sap.m.ListItemBase, 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 contains an error, for example within the global edit flow, add the string (Contains errors) to the text of the item and highlight the row accordingly.

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: AddCollapse AllExpand 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.

Add Items

For adding items, place an Add or Create text button on the toolbar.

  • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
  • Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the tree or node:

  • If nothing is selected, add the new item to the root.
  • If a single node is selected, add the new item to the selected node.
  • If a single leaf is selected, add the new item as a child of this leaf. The original selected item becomes a node.

If your tree doesn’t support adding items to the root, selected node, or selected leaf, disable Create or Add for the corresponding levels.

Disable Create or Add if more than one item is selected.

Enable the shortcut Ctrl+Enter to trigger the Add and Create buttons.

For more details, see guidelines for managing objects (including subarticles).

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that tells the user how many items will be affected. Let users choose whether to apply the action anyway or cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element – States.

If the action was applied and the items are still available, keep them selected.

Message for an action that applies to a part of a selection
Message for an action that applies to a part of a selection

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.

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. Also, because there is no generic keyboard interaction, drag and drop isn’t accessible. Moreover, drag and drop is not available on all browsers. For these reasons, offer drag and drop only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.

Use drag and drop only in addition to existing visible UI elements
Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within a tree, use the following options:

  • For dropping items as a child, use whole nodes as drop targets (sap.ui.core.dnd.DropPosition.On).
  • For dropping items on the same level, use the space between items as drop targets (sap.ui.core.dnd.DropPosition.Between).
  • If you want to allow users to drop items as a child or sibling, offer both drop targets (sap.ui.core.dnd.DropPosition.OnOrBetween).

This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Do not combine rearranging items within one level and sorting. If you really need to do so, make sure there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

Moving items from one node to another can be combined with sorting without any issues.

Drop targets in between items
Drop targets in between items

Visible Alternatives to Drag and Drop

Depending on the functionality you need, use one or more of the following alternatives:

  • To move items up or down within a node:
    Use the  Move Up and  Move Down buttons on the toolbar. These buttons move the selected items until the first selected item can’t be moved up or the last selected item can’t be moved down any further.
    Depending on your tree, this can make sense for both leaves and nodes, only for leaves, or only for nodes. When moving a node, move the whole node and (if applicable) all its children up or down to the next position within the parent node.
    Always make sure that when the user moves an item in one direction and then moves it back, the order is the same as it was before.
    Do not combine the option to move items up and down with sorting.
  • To move items to another node:
    Use Copy and Paste buttons on the toolbar.
    Alternatively, offer a Move To button. Clicking Move To opens a dialog that shows all the nodes of the tree, but no leaves. Selecting an item in this dialog closes the dialog and moves the corresponding items to the selected node.
  • To change the level of an item:
    In some trees, such as document structures, users can change the level of an item without affecting the level of parent or child items. In this case, use left and right arrow buttons (   ).

Filtering

What exactly needs to stay or be removed is highly dependent on the kind of structure and data your tree displays. For many trees, the following approach works well if you want to apply filters only to the leaves of a tree:

  • Remove all leaves that don’t fit the filter criteria
  • Remove empty nodes

If you also apply filters to nodes, keep the following in mind:

  • A node may or may not fit the filter criteria.
  • A node can contain items (nodes and/or leaves) that fit the filter criteria.

Because of this, the results might contain more nodes than those that are relevant for the filter criteria.

Information
The tree control itself has no influence on the filter result. It sends a filter request and displays whatever comes back. Make sure that the result set is meaningful.

Sorting

Before you start, ask yourself if sorting is meaningful in your tree. If so, decide on a meaningful default sort order.

If sorting is meaningful, is it meaningful on all levels? Or does the tree structure need to be stable? In the latter case, sort only leaves, but not nodes.

The descending sort order must always be the exact reverse of the ascending sort order. Use a meaningful sort order. For example:

  • Sort text alphabetically
  • Sort numbers by their value
  • Sort status information by the severity of the status:
    • Ascending: Sort status information from positive to negative, with neutral last.
    • Descending: Sort status information from negative to positive, with neutral first.
    • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
    • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting the tree data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button
'Export to Spreadsheet' menu button

Resources

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

Elements and Controls

Implementation

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 tableform 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. By contrast, the analytical table supports only a very limited set of controls.
  • The focus is 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 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 expect the table to contain more than around 1,000 rows. Try using the analytical table or grid table instead; they are easier to handle, perform better, and are 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 be more appropriate because each cell contains only one data point. By contrast, the responsive table offers greater flexibility within line items, including the ability to add more data points per cell and 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 child nodes. 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 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 use a responsive table as a form
Don't 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 responsive table is optimized for viewing one line item at a time with no scrolling 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 for the corresponding cell is provided as a label/value pair. The label is defined by the column header, and the value is taken from the corresponding cell. Labels can be displayed next to the value or above the value.

Within the pop-in area, the label/value pairs can be displayed in the following ways (sap.m.Table, property: PopinLayout):

  • Block: Label/value pairs are listed one below the other.
  • GridSmall: Label/value pairs are displayed next to each other in equally spaced grid cells. An additional column is shown for each 13 rem of available width (208 px with default browser settings). If the number of grid cells exceeds the available width, the grid cells wrap. On S size, this layout transforms automatically to a block layout.
  • GridLarge: The display logic is the same as for GridSmall,, but grid columns come with a larger minimum width (26 rem instead of 13 rem).

In all layouts, you can show the labels next to or above (recommended) the corresponding data.

The responsive table uses all the available space, and does not provide any padding. If there is space around the table, it comes from the spacing defined for the surrounding layout container.

Information
The GridSmall and GridLarge layouts are not available in all browsers. If the chosen layout is not available, it is automatically changed to Block layout.
Responsive table displayed on a smartphone (size S)
Responsive table displayed on a smartphone (size S)
Responsive table displayed on a tablet (size M)
Responsive table displayed on a tablet (size M)
Responsive table displayed in compact mode on a desktop computer (size L)
Responsive table displayed in compact mode on a desktop computer (size L)

The responsive behavior is optional. If it is not used, the responsive table just minimizes all visible columns until they are no longer readable.

There are two ways to configure responsiveness: auto pop-in mode and manual pop-in mode (sap.m.Table, property: autoPopinMode).

The auto pop-in mode ensures responsiveness automatically and is sufficient in most cases. You can still influence the behavior per column, but only to a limited extent.

The manual mode is more flexible, but needs are more configuration. This configuration becomes more cumbersome when table columns can be shown/hidden or re-ordered. On the other hand, only the manual mode allows you to:

  • Let more than one column stay in the tabular layout
  • Move more than one column into the pop-in area at once

In both modes, the responsive table ensures that at least one column always remains in the table layout.

Auto Pop-In Mode

The auto pop-in mode handles responsiveness automatically. You can optimize this to a certain extent by adapting the behavior per column.

Columns have a minimum width. As soon as the width of all the visible columns exceeds the table width, the right-most column moves to the pop-in. The default minimum width per column is 8 rem. You can change this value for each column (sap.m.Column, property: autoPopinWidth).

To further influence the behavior, you can assign columns a priority. Low-priority columns move to the pop-in first (right-most low priority column first), medium-priority columns next, and high-priority columns last. The default priority is “none”, which is handled like the “medium” priority (sap.m.Column, property: importance).

Instead of moving columns to the pop-in area, you can also hide columns of one or more priority levels (property: hiddenInPopin).

In auto pop-in mode, all other pop-in-related column settings are ignored.

Manual Pop-In Mode

The manual pop-in mode allows more flexibility but also requires more effort if you want it to work in a meaningful way. You also need to invest additional effort if table columns can be shown/hidden or re-ordered.

You need to configure each column manually. Depending on the width of the table (in pixels), the column needs to know which of the following responses is required:

  • Stay in the table layout (in auto pop-in mode, only one column stays in the table layout).
  • Move to the pop-in (sap.m.Column, with the properties: demandPopin, minScreenWidth, popinHAlign, popinDisplay).
  • Hide

By default, the table width is assumed to be the screen width. If the table does not use the full width of the screen, app developers must configure the table accordingly (sap.m.Table, property: contextualWidth).

Because you configure the pop-in response for each column individually, you can also handle more than one column at a given breakpoint. This allows you to move several columns to the pop-in area at once, which isn’t possible in auto pop-in mode

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

Example for Block Layout

A typical responsive table.

A typical responsive table
A typical responsive table

Hide the information column for a width smaller than 570 px.

Hiding the information column
Hiding the information column

Move the column “vendor” to the pop-in area for a 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 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 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 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

Example for GridLarge Layout

A more complex responsive table.

A more complex responsive table (full screen without pop-in)
A more complex responsive table (full screen without pop-in)

In this example, the Average Occupancy Rate and Available In columns move to the pop-in area if the screen width is less than 1900 pixels.

GridLarge layout - 'Average Occupancy Rate' and 'Available In' columns move to the pop-in area
GridLarge layout - 'Average Occupancy Rate' and 'Available In' columns move to the pop-in area

If the width is less than 1500 pixels, the Average Stay column moves to the pop-in area.

GridLarge layout - 'Average Stay' column moves to the pop-in area
GridLarge layout - 'Average Stay' column moves to the pop-in area

If the width is less than 1100 pixels, the Description column moves to the pop-in area. Since all four columns in the pop-in area do not fit into one row, the pop-in wraps.

GridLarge layout - 'Description' column moves to the pop-in area
GridLarge layout - 'Description' column moves to the pop-in area

If the width is reduced even further, the Details column moves to the pop-in area. On this narrow screen, only one column fits into one pop-in row, so it looks exactly like the block layout.

GridLarge layout - 'Details' column moves to the pop-in area
GridLarge layout - 'Details' column moves to the pop-in area

Layout

The optional title bar consists of the title of the responsive table, an item counter, variant management, and the toolbar.

The filter info bar appears when the responsive table is filtered, and 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 contains the title of the responsive table, an item counter, 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 AddEdit, 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 within 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, see object display components.
You can use the table footer to display additional static information relating to the table content.
The More button loads more items to the front end if not all items have yet been loaded.
Components of the responsive table
Components of the responsive table

Behavior and Interaction

The responsive table is quite flexible with regard to its content.

Table Level

Scroll

The height of the table is defined by the number 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 triggered by scrolling (preferred), or by clicking the More button.

Same table, different number of items
Same table, different number of items

When the user scrolls, the title bar, column headers, and filter info bar can stick to the top of the surrounding layout container (sap.m.Table, property: sticky).

Information
The “sticky” feature comes with some limitations:

  • It is not available on all browsers. In non-supporting browsers, the corresponding areas (title bar, column headers, filter info bar) are not fixed on top of the surrounding layout container while scrolling.
  • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the table is placed within the object page.
  • If focus is set to a fixed column header, the table is automatically scrolled to top.

Sticky table title and sticky column header
Sticky table title and sticky column header

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.
  • If the corresponding column can contain blank cells. Otherwise, it is cumbersome to differentiate between blank values and merged values.
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 modes (sap.m.Table/ sap.m.ListBase, property: mode):

  • None: Items cannot be selected (sap.m.ListMode.None).
    Beware: Line items can still use the sap.m.ListType “navigation”, which allows click handling on specific line items. Only use this option if the click triggers navigation to a corresponding line item details page.
  • Single selection master: One item in the responsive table can be selected. Items are selected by clicking the whole row. The single select master mode has no obvious visual cues, such as checkboxes or radio buttons. It only provides a light blue background for the selected state. Because of this, it can barely be differentiated from tables without selection (mode: None). Single select master is the preferred mode for single selection (sap.m.ListMode.SingleSelectMaster).
  • Single selection left: One item in the responsive table can be selected. For this, the responsive table provides radio buttons on the left side of each line item. Only use this mode if row clicks are being used for something else, such as navigation. (sap.m.ListMode.SingleSelectLeft).
  • Multiple selection: Users can select one or more items using the checkboxes on the left side of each line item. The Shift key can be used to select a range. Users can (de)select all items using the Select All checkbox to the left of the column header. Select All should (de)select all items that the user can reach by scrolling.  (sap.m.ListMode.MultiSelect).
Single selection master
Single selection master
SIngle selection left, with radio buttons. Use only if row clicks are used for something else.
SIngle selection left, with radio buttons. Use only if row clicks are used for something else.
Multiple selection
Multiple selection

Group

For grouping items, a group header is displayed (sap.m.GroupHeaderListItem). 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 items already loaded 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 in growing mode. 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 'Delete' mode
Responsive table in 'Delete' mode

Highlight an Item

To highlight an item, use the “highlight” indicator (sap.m.ColumnListItem, properties: highlight).

Highlighted item
Highlighted item

Navigate

To allow navigation from a line item, use an item with the type “navigation” (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This creates an indicator at the end of the line (“>”) and the entire line item becomes clickable. If the user clicks on the line, 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.

By contrast, clicking an interactive control within a line item does not trigger the navigation event. Instead, the corresponding control handles the click event.

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

Indicate Navigated Item

When multi-selection is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case only (multi-selection table with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.ColumnListItem, property: navigated).

Navigated item
Navigated item

Edit Line Items

To allow editing for a line item, 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, for example, 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

Drag and Drop

One or several items can be repositioned within a table or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop
Whole item as drop target
Whole item as drop target

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column). Context menus can be implemented for a specific table or row.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or SHIFT+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Responsive table with a context menu
Responsive table with a context menu

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

Alongside textual elements, you can also add any control to a table cell, such as input fields, microcharts, buttons, and so on.

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.

With the View Settings dialog, users can sort, filter, and group by each of these data points.

Several controls per cell
Several controls per cell

You can also have different controls in different rows in the same column. This could be the case if one item is locked, but another item is in edit mode, for example.

Different controls per column
Different controls per column

Guidelines

Responsiveness

In most cases, the auto pop-in mode is sufficient. If you need to optimize further, first try to adapt the columns to influence the automatic behavior (sap.m.Column, properties: autoPopinWidth, importance). For example, set the priority for the two or three most important columns to “High” (identifying column, key attribute).

While the pop-in layouts GridLarge and GridSmall make better use of the available width, they also only look good with content that is specifically designed for these pop-in layouts. If you have text-only tables with only one value per column, use the Block layout (sap.m.Table, property: popinLayout).

Place the column header labels in the pop-in area above the corresponding values (sap.m.Column, property: popinDisplay, value: Block). This avoids alignment issues with different content. Be aware that the labels get top-aligned with the adjacent content.
Only place the label next to the corresponding value under the following conditions (sap.m.Column, property: popinDisplay, value: Inline):

  • The values are text-only (no input fields, icons, images, micro charts, and so on)
  • The available space is at least the double the width of size S.

This avoids truncation or “over-wrapping” of the labels and content.

If a column does not have a column header text (for example, if it always contains the same button with its own label), do not show the header text as a label in the pop-in area either (sap.m.Column, property: popinDisplay, value: withoutHeader). If you forget this setting, you will see an empty space followed by a colon (“:”).

Information
The GridSmall and GridLarge layouts are not available in all browsers. If the chosen layout is not available, it is automatically changed to Block layout.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the responsive table. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning
The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

  • The number of rows in the table
  • The number of displayed columns
  • The complexity of the cell content (for example, simple text vs. complex charts)
  • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
  • The browser being used

Table Title

Implement the table title by using a title control in a toolbar.

Use a table title only if the title of the table is not indicated in the surrounding area. Do not use a table title if it simply repeats text that is already above the table. For example:

  • A pricing conditions table is the only control on a tab labeled Pricing Conditions.
  • A section or subsection on an object page contains only one table.

Use a table title if you need the item count, table toolbar, or variant management. To avoid repeating text, feel free to use generic text as a table title, such as Items.
Exception: If the surrounding area contains the table title, and both the item count and toolbar can be added to the surrounding area, no additional table title is needed.
Example: An object page (sub-)section contains only one table. In this case, add the item count and the table toolbar to the (sub-)section header.

Developer Hint
Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table.

If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

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)

The item count in the table title includes all the visible items that a user can reach by scrolling. Group headers are not included.

Remove the item count in the table title if there are zero items. Do not use an item count together with “growing mode”.

If possible, keep the title bar sticky (sap.m.Table, property: sticky).

Table title with item count
Table title with item count

Selection

If the click area for the row is being used for another purpose (such as navigation), it cannot be used for selecting the row. In this case, use the “single select left” selection mode, which offers a radio button as an additional click area for each row. To avoid confusion, make sure that the first data column does not contain radio buttons in default delivery.

In all other single selection cases, use the selection mode “single select master”.

For all single selection modes, make sure that one item is initially selected. Otherwise, the user cannot return to the initial state. A selected item can only be deselected by selecting another item.

In multiple selection mode, do not show checkboxes in the first data column in the default delivery to avoid confusion. Offer the Select All checkbox for (de)selecting all items the user can reach by scrolling.

Don't
Single selection left - Don't show radio buttons in the first column in the default delivery
Single selection left - Don't show radio buttons in the first column in the default delivery
Don't
Multiple selection - Don't show checkboxes in the first column in the default delivery
Multiple selection - Don't show checkboxes in the first column in the default delivery
Do
Use the selection mode
Use the selection mode "single select left" if clicking the row is used for something else (such as navigation)
Do
Use the selection mode
Use the selection mode "single select master" in all other single-selection cases
Developer Hint
Select All is only applied to items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded, such as items added via lazy loading with growingScrollToLoad. This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

To process all items, listen to the selectionChange event and to its selectAll flag. This indicates whether the Select All checkbox was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

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 three to five columns if the responsive table is shown within the flexible column layout. Use about eight columns if using the full screen width, depending on the content.

If the responsive table does not fit into the width provided:

  • 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 into the width provided, 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, no column header label is needed as long as at least one column still has a column header label.

Use controls that wrap and support wrapping with hyphenation, such as text (with wrapping and hyphenation enabled). Do not use controls that truncate.

Keep column headers sticky.

Do
Wrap column headers
Wrap column headers
Don't
Don't truncate column headers
Don't 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 (rarely used)
Accepted: Link as column header text (rarely used)
Accepted if responsiveness is taken into account: Text plus search field
Accepted if responsiveness is taken into account: Text plus search field

If a column cell contains several fields, use an umbrella term in the column header (such as Address for fields like Street, ZIP Code, and City).

For text and ID fields, use a generic label (for example, Employee for Name and ID).

If none of these are possible, separate the labels with “/” (for example, Name / Status).

For boolean values, such as checkboxes, find a descriptive text for the column header.

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.

Exception: Secondary information in a column always follows the alignment of the main information.

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

Left-align status information.

Left-align status information
Left-align status information

Center-align icons.

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
Use top-alignment where possible
Use top-alignment where possible
Don't
Don't use top alignment if it doesn't make sense
Don't use top alignment if it doesn't 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 table 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
If displayed as a link, use the whole text as the link
If displayed as a link, use the whole text as the link

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
Is displayed as a link, use only the first line as the link
Is displayed as a link, use only the first line as the link

If there is more than one key identifier (for example, First Name and Last Name), display these columns first and show the values in bold text.

Several key identifiers
Several key identifiers

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 and support hyphenation.

For example, use text.

Do
Wrap text
Wrap text
Don't
Don't truncate text
Don't truncate text

For editable content, use input fields and other interactive controls within the table cells. If you need to offer edit mode, change your text controls (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 – Inline
Interactive controls – Inline

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

Flag and Favorite

Place the flag or favorite marker in the first column (in the default delivery). To change the settings, users need to drill down into the object itself.

Item marked as a favorite
Item marked as a favorite

Empty Tables

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

Examples:

  • If a table is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the table with data.
  • If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    To start, set the relevant filters.
  • If a table is used together with a filter bar and the filter does not return results, use the following text:
    No data found. Try adjusting the filter settings.

Adapt the texts above if:

  • The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of filter settings).

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 contains 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. To do this, use an object status control with the error state (sap.m.ObjectStatus, property: state, value: sap.ui.core.ValueState.Error).

In addition, highlight the row accordingly (sap.m.ListItemBase, property: highlight).

A modified item with an error
A modified item with an error

To show that an item is locked, use a transparent button with the corresponding icon and the text Locked by [Name] at the bottom of the identifying column. The user can click 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 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, you can show a highlight indicator next to the item. The highlight indicator can indicate:

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It doesn’t tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted items using status colors
Highlighted items using status colors
Highlighted items using industry-specific (indication) colors
Highlighted items using industry-specific (indication) colors

Numbers and Units

If the following conditions all apply, show the unit of measurement in the column header:

  • The unit of measurement is the same for all rows
  • A single cell contains only one amount with the unit of measurement
  • The column header does not scroll away

In all other cases, show the unit of measurement together with the corresponding amount within the row.

Show the unit of measurement in the same column as the corresponding amount.

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 table width is narrow, 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)

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, it is not accessible, since there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.

Use drag and drop only in addition to existing visible UI elements
Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within the table, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop targets in between items
Drop targets in between items

Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on values in a column, the dropped item needs to take on the value of the target group for the corresponding column. If this is not wanted, do not allow users to rearrange items in grouped tables.

Example:
A table is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Don't
Don't combine rearranging items with grouping, unless you know exactly what you're doing.
Don't combine rearranging items with grouping, unless you know exactly what you're doing.

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

The context menu can be triggered for the whole table or per row.

Actions

To trigger actions on multiple items, use a multiselection table (sap.m.Table, property: mode, value: sap.m.ListMode.MultiSelect), and offer the corresponding actions on the table toolbar. Keep the table toolbar sticky (sap.m.Table, property: sticky).

Do not offer actions for 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. One example would be an Add to Cart button in a shopping application. 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 a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.
Inline actions
Inline actions

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Give users the option to apply the action anyway or to cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element – States.

If the action was applied, and if the items are still available, keep them selected.

Message for an action that applies to a part of a selection
Message for an action that applies to a part of a selection
Place actions near to the objects to which they belong
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

For adding items, place an Add or Create text button on the table toolbar.

  • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
  • Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the table, with a visual highlight at the beginning of the row.

There are three options for adding an item after the Add button is pressed. In order of priority (most recommended first), these are:

  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 just a few columns and no option to hide columns.
  2. Open a dialog for larger tables with up to 8 editable 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 that cannot be handled by a dialog (for example, tables with more than 8 columns). When the user presses Save in the footer toolbar of the create page, navigate back to the table.

A new item can have three different states:

  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 to keep the item visible.
  3. As soon as the responsive table is sorted, filtered, or grouped again, the action is also applied to the new item. It then also loses the visual highlight.

In the context of the draft handling new items are not saved on table level, but rather with the entire draft.

For more details, see the guidelines for managing objects (including subarticles).

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 highlighted, still the first item
Saved new item, still highlighted, still the 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.

For details, see mass editing.

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)

Sort

For the default sort settings, sort by the column that identifies the row, which is usually the first column in default delivery. From this column, use the primary data point.

If you offer sorting, offer it for each data point. In other words, allow sorting by both the primary and secondary information in a column. Allow sorting in both directions, ascending and descending. The descending sort order must always be the exact reverse of the ascending sort order.

For each data point, provide a meaningful sort order. For example:

  • Sort text alphabetically
  • Sort numbers by their value
  • Sort status information by the severity of the status:
    • Ascending: Sort status information from positive to negative, with neutral last.
    • Descending: Sort status information from negative to positive, with neutral first.
Object status sorted ascending, with neutral status last
Object status sorted ascending, with neutral status last
Object status sorted descending, with neutral status first
Object status sorted descending, with neutral status first
    • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
    • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.
Object status sorted ascending and alphabetically, from positive to negative with neutral last
Object status sorted ascending and alphabetically, from positive to negative with neutral last
Object status sorted descending and alphabetically, from negative to positive with neutral first
Object status sorted descending and alphabetically, from negative to positive with neutral first

Filter

To display the current filter state, use the info bar below the table title. Clicking 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.

Keep the info bar sticky (sap.m.Table, property: sticky).

Developer Hint
To display the current filter settings on the info bar, consider using the list formatter (sap.ui.core.format.ListFormat).
Filtered table
Filtered table

Group

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

If there is no grouping value, show the following text:
[Label of the grouped column]: (Not Available)

This is the case if you have a group of items that don’t have a value for the grouped column.

Grouped table, with missing grouping value
Grouped table, with missing grouping value

Persist the view settings. When a user reopens the app, show the responsive 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.

If all columns are hidden, the table shows a corresponding “no data” text.

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.

Tables in Object Pages

To show a table in the object page content area, use the responsive table.

A responsive table with up to 20 expected items can be displayed right away, without lazy loading.
If you expect the table to have more than 20 items, use one of the following 3 options:

  1. Lazy loading (More button): Use this option if you expect to have up to 100 items.
  2. Tab navigation: If you expect to have more than 50 to 100 items, but less than 400, use the object page with tab navigation instead of anchor navigation. Put the table on a dedicated tab.
  3. Navigation to a list report: If you expect the table to have more than 400 items, or if the tab approach is unsuitable, restrict the number of items in the table itself to a reasonable amount. To provide the user with a way to work with the entire table, offer navigation to a separate list report containing the full table.

For all of the three options mentioned above, we recommend providing a search, and if feasible, sort and filter capabilities for the table in the object page. Grouping should be avoided.

For more information on the use of tables within the object page, see the Tables section of the Object Page article.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting table data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button
'Export to Spreadsheet' menu button

Paste

To paste data from the clipboard to the table, the browser functionality for paste can be used (CTRL + V or browser context menu).

  • If the focus is on row level, the app has to take the data from the clipboard and add it to the corresponding controls within the table.
  • If the focus is on an editable control within the table, the control gets the data automatically.

Pasting via context menu does not work if a custom context menu is used.

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 for a large 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: inset 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.
  • The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). 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

Tree Toolbar

The tree toolbar always appears above a tree or tree table. The control is used for key actions that impact the entire tree.

Usage

Use the tree toolbar if:

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

Don’t use the tree toolbar if:

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

Responsiveness

To enable responsiveness, use the overflow toolbar control. For more information, see Toolbar Overview – Responsiveness.

Components

The tree toolbar can contain several components, including a title and several types of button. Actions are grouped by the following action types:

  • Finalizing actions, such as Save or Cancel. Finalizing actions are app-specific, and are used only if the tree is editable.
  • Business actions, such as Edit or Create. Business actions can be app-specific or general object management actions. They also include actions for organizing the tree.
  • Actions for managing the content, such as Sort or Filter. These settings are also known as “view settings”.
  • Actions for managing the layout, such as Maximize or Minimize.
  • Generic actions, such as Export to Spreadsheet.

Between the groups, add a separator line.

The following content can be part of the tree toolbar. Use only the content your users really need. For the remaining content, keep the order shown below:

  • Title
  • Variant management or content switch (for example, as used to switch between multiple views in a list report)
  • Search
  • Finalizing actions:
    • Save
    • Cancel
  • Business actions: Use this action type for app-specific actions. This group contains:
    • App-specific business actions
    • Actions for object management
      • Create (for new items) or Add (for existing items)
      • Edit
      • Delete (if the object itself is deleted) or Remove (if the reference to an item is removed)

The order of actions in this group is not “fixed”. Place the most important action first, followed by the second most important action, and so on. Try to keep Create/Add, Edit, and Delete/Remove together, but only if this is meaningful in your app.

  • Actions for organizing the tree:
    • Cut
    • Copy
    • Paste and / or Paste from Spreadsheet
  • Actions for content management (view settings):
    • Collapse All / Expand All
    • Sort
    • Filter
    • Group
    • Column Settings
  • Actions for managing the layout:
    • Maximize / Minimize
  • Generic actions:
  • View switch (for example, to switch between tree and chart view)
  • Overflow
All mentioned components in the correct order
All mentioned components in the correct order

Behavior and Interaction

App-Specific Business Actions

If needed, you can define your own actions for the app. In this case, use text-only buttons with a short, unambiguous text for the action that the button performs. A button text is usually a single-word verb (for example, Share). Note that text strings can be longer in other languages.

Tree toolbar with app-specific buttons
Tree toolbar with app-specific buttons

Title

A title provides a short, meaningful summary of the content, mostly in a single word. To display a title, use the title control.

In addition, the title can be followed by an item counter (the number of items in parentheses).

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

Title with item counter in the tree toolbar
Title with item counter in the tree toolbar

Variant Management

In trees, a variant stores all the settings that define the table view, such as the column layout, column visibility, sorting, filter settings, and grouping. The variant management control enables users to load, save, and change variants. In most cases, variant management replaces the title.

Variant management in the tree toolbar
Variant management in the tree toolbar

Title and Variant Management

If you need both a title and variant management, place the variant management control directly after the title. Use a separator between the title and variant management.

However, since displaying both the title and variant often results in truncated texts, this pattern is not recommended.

Title with variant management
Title with variant management

Content Switch

To switch between different predefined views, use a select control or a segmented button. The content switch replaces the title and the variant management control. In the rare case that the content switch is shown together with a title, the content switch follows the title.

A predefined view contains settings for sorting, filtering, grouping, column layout, and column visibility. However, in most cases, the content switch is just used for different filter settings like All, Mine, and Others. In this case, make sure that the content switch doesn’t interfere with other filter settings. For example, remove the corresponding filter from the filter bar. If possible, include an item counter per view.

Another common pattern for content switches are views like By X, and By Y, which are usually defined using group settings.

Use the segmented button and the select control as follows:

  • For a limited set of views (2-3), use the segmented button for desktop and tablet devices. Replace it with a select control if there is not enough screen space.
  • If the number of views can change or is larger than 3, use the select control.

For more information, see multiple views for list reports.

Segmented button with a counter
Segmented button with a counter
Segmented text button to switch content
Segmented text button to switch content
Select control to switch content
Select control to switch content

Search

For trees with a large number of items, consider adding a search field. Use a search field only if there is no other way to search within the tree (for example, if there is no additional filter bar).

Place the search field on the right side of the toolbar. Since the search field cannot be moved into the overflow menu, always provide a minimum width.

Ideally, search for results in all columns. As a minimum, search in all currently visible columns.

For more information, see Search.

Search in the tree toolbar
Search in the tree toolbar

Create / Add

Use a text button for Create or Add actions. If the Create or Add action is a main function, never move it into the overflow.

Insert the new item at the following position:

  • If a single node is selected, insert it as a child item to this node
  • If a single leaf is selected, insert it as a sibling to this leaf (within the same node)
  • If no item is selected, insert it into the visible “root” node

If multiple items are selected, disable the Create / Add button.

More information: Object Handling (Create, Edit, Delete)

Tree toolbar with 'Create' button
Tree toolbar with 'Create' button
Tree toolbar with 'Add' button
Tree toolbar with 'Add' button

Edit

There are several options for editing a tree:

Edit a Single Item

To allow the user to edit a single item, show an icon-only Edit button at the end of the item (depending on the tree control, use sap.m.TreeItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive; or row actions). The user can click the button to trigger the edit event. Use this event to make the item editable.

Editing a single item
Editing a single item

Mass Editing

See: Mass Editing

Edit the Whole Tree

To let the user edit a whole tree, use a text-only Edit button. When the user triggers the edit action, switch the table to edit mode. In edit mode, don’t show the Edit button and add the finalizing actions Save and Cancel instead. Remove any actions that are meaningless in edit mode. Keep the view settings available.

More information: Manage Objects

Tree toolbar in display mode with 'Edit' as the most important action
Tree toolbar in display mode with 'Edit' as the most important action
Tree toolbar in edit mode
Tree toolbar in edit mode

Delete / Remove

Use a text button for Delete or Remove actions. In most cases, Delete is used together with Create, while Remove is used together with Add.

If the Delete or Remove action is a main function, never move it into the overflow.

More information: Manage Objects

Tree toolbar with 'Delete' button
Tree toolbar with 'Delete' button
Tree toolbar with 'Remove' button
Tree toolbar with 'Remove' button

Cut, Copy, Paste

Use icon-only buttons for Cut and for Copy. Offer these actions if the tree structure is editable. Always pair them with drag and drop.

For Paste, use either an icon-only button or an icon-only menu button. In the menu, offer:

  • Paste: to paste cut/copied rows
  • Paste from Spreadsheet: to create new rows with data from the clipboard. Since the clipboard can’t be accessed directly, use this button to show a hint on how to paste via short cut (CTRL + V) or browser context menu.

When pasting, insert the item(s) in the following position:

  • If a single node is selected, insert it as a child item to this node
  • If a single leaf is selected, insert it as a sibling to this leaf (within the same node)
  • If no item is selected, insert it into the visible “root” node
Tree toolbar with 'Cut' button, 'Copy' button, and 'Paste' menu button
Tree toolbar with 'Cut' button, 'Copy' button, and 'Paste' menu button

Collapse All, Expand All

Use icon-only buttons for Collapse All and Expand All.

Collapse All closes all nodes up to the visible root level: only items on the first visible level are shown. Expand All opens all nodes down to the lowest level: all items are visible.

Tree toolbar with 'Collapse All' and 'Expand All' buttons
Tree toolbar with 'Collapse All' and 'Expand All' buttons
Developer Hint
To implement the Expand All option, use the expandToLevel method and define a very high number of expendable levels. Bear in mind that expanding every single level takes time, which can have an adverse effect on performance if you are working with deep trees. Weigh this up very carefully before offering Expand All for deep trees.

Sort, Filter, Group

When the user chooses one of these actions, open the view settings dialog or the P13n Dialog with only the corresponding settings.

  • If sorting, filtering, and/or grouping is a common use case in your app, offer one, two, or all three of the corresponding features. Don’t provide these features if the tree is expected to have only a small number of entries (up to 20 in most cases).
  • If filtering is a main use case, don’t offer filtering on the tree toolbar; use the filter bar instead.

Only use the view settings you really need. For example, don’t offer grouping if it doesn’t support your use case.

Ensure a consistent user experience. When a user reopens the app and variant management is not used, show the tree with the same view settings last defined by this user.

For more information, see Table Personalization.

Triggers for the different view settings (sort, filter, and group)
Triggers for the different view settings (sort, filter, and group)

Column Settings

Use the table personalization dialog or the P13n Dialog for adding, removing, and rearranging columns.

Offer column settings 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.

Ensure a consistent user experience. When a user reopens the app and if variant management is not used, show the tree with the same column settings last defined by this user.

For more information, see Table Personalization.

Tree toolbar with 'Column Settings' button
Tree toolbar with 'Column Settings' button

Maximize / Minimize

Use an icon-only button for Maximize or Minimize. Offer the Maximize button to open the same tree sized to fit the full screen. When maximized, offer the Minimize button to go back to the standard view.

Export to Spreadsheet

The Export to Spreadsheet action allows the user to export table rows. It is represented by an icon-only menu button.

Tree toolbar with the 'Export to Spreadsheet' menu button
Tree toolbar with the 'Export to Spreadsheet' menu button

Print

The action for printing tree items is represented by an icon-only button.

Tree toolbar with 'Print' button
Tree toolbar with 'Print' button

View Switch

View switches are right-aligned in the toolbar and allow the user to switch between different chart types and different controls for displaying items (for example list, grid list, tree, tree table). Provide the view switch if a chart relies on subtle color differences or gradients of color. In these cases, users with visual impairments can switch to the tree view.

Switches are optional: they don’t have to be provided if there is no need to switch between different charts or trees.

Define the number of chart types and switches with care. Offer only chart types that help to visualize the respective data and that best assist the user. Ideally, offer no more than three types of visualization.

The sequence of chart type switches is not fixed. Sort them in order of importance.

The chart type currently in use is highlighted. To show this, use a segmented button with icons.

For more information about the icons and the chart types they represent, see Chart Toolbar.

Overflow

More information: Toolbar Overview – Overflow.

Styles

On the tree toolbar, use the following button styles:

  • If the single primary action for the whole page is on the tree toolbar, use the emphasized button style.
  • if the single primary action for the whole page is not on the tree toolbar, you can still highlight the most important button by using the ghost button style.
  • For secondary actions and negative path actions, use the transparent button style.
  • For split buttons and menu buttons, use the transparent button style.
  • Don’t use semantic button styles on the tree toolbar.

For more information, see Button and Action Placement.

Guidelines

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items are affected. Let the user choose whether to apply the action anyway or cancel it.
  • Only disable the action if it can be applied to none of the selected items.

For more information, see UI Element States.

Message for an action that applies to a part of a selection
Message for an action that applies to a part of a selection

If the items are still available after the action was applied, keep them selected.

For further guidelines, see Toolbar Overview – Guidelines.

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

3D Viewport

You can use the the 3D viewport control to enable 3D viewing in your SAP Fiori application. This control is available in the Visual Interaction toolkit library. The 3D viewport control can display simple and complex 3D objects in SAP Fiori, and offers basic user interaction with the 3D environment and its objects.

3D objects in the 3D viewport control
3D objects in the 3D viewport control

You can use the 3D viewer in various locations in the app, such as the object page, the dynamic side content control, dialogs, or popovers.

Usage

Use the 3D viewport control if:

  • You want to show 3D models in an SAP Fiori environment.
  • You want to let users view 3D files in the browser without downloading any browser plugins.
  • You want to enable users to interact with 3D models stored locally or remotely.
  • You want to load multiple 3D models at the same time.

Do not use the 3D viewport if:

  • There is not enough space for users to interact with 3D content (in other words, the 3D viewport is too small to interact with 3D models).
  • You require simple visual representations of objects or functions. In this case, use sap.m.Image instead.

 

Developer Hint
The 3D viewport control was designed to help developers load and display 3D content quickly and easily. It does not require knowledge of 3D space or the programming techniques needed for correct data visualization.

If you need more control over the elements in the 3D viewport, or if you require extended functionality, you can use an API within the Visual Interaction toolkit to manipulate or interrogate 3D content.

The 3D viewport control uses the SAPUI5 logging mechanism to log various messages, which may include information, warnings or errors. For more information, see the SAPUI5 log page: https://ui5.sap.com//sdk/#/api/jQuery.sap.log

Responsiveness

If you use the 3D viewport in conjunction with SAP Fiori page layouts or floorplansresponsiveness is determined by the respective layout or floorplan, such as the dynamic page layout or flexible column layout.

The 3D viewport adjusts its size to fit within the available space.

Example: 3D viewport within an object page - Sizes XL/L, M, and S
Example: 3D viewport within an object page - Sizes XL/L, M, and S

Behavior and Interaction

The 3D viewport supports a range of specific mouse and touch gestures by default. The available gestures are determined by the viewport component with which you interact.

When a 3D model is loaded into the 3D viewport, you can pan, zoom, rotate, and click or tap the model with the following actions:

Action Touch Gesture Mouse Gesture Keyboard Shortcut
Select or deselect an object in the scene Tap Left click N/A
Zoom onto and visually focus on an object in the scene Double tap Double click N/A
Rotate the scene Tap and drag Left click + drag Cursor keys
Pan the scene Two-finger tap and drag Hold mouse middle button and drag

or

Hold both left and right buttons and drag

Shift + cursor keys
Zoom out of the model Pinch Mouse wheel scroll forward

or

Right click + move mouse up

Minus key (-)
Zoom into the model Stretch Mouse wheel scroll backwards

or

Right click + move mouse down

Plus key (+)

 

 

The recommended selection behavior is known as “sticky” selection (default):

  • When a user clicks on an object, it is marked as selected.
  • Clicking another object selects that object, along with all previously selected objects.
  • Clicking a selected object deselects it.
  • Clicking empty space deselects all objects.
Information
There are no keyboard shortcuts for object selection. As a scene can have thousands of objects, direct interaction with the Viewport using a pointing device is required to select objects.

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

Busy Indicator

Intro

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 part of a screen that has multiple controls, and:

  • You need to display additional information, or,
  • The user needs to be able to cancel the operation.

Examples

  • File Upload: The file upload dialog contains 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 to be uploaded.
Example: Busy indicator for file upload
Example: Busy indicator for file upload
  • Table Rows: Each row in the table has an action related to the table item. Clicking the Run button in a specific row changes status of the current item. The user is still able to work on the other items or cancel the current operation.
    Since each SAPUI5 control 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.
Example: Busy indicator in table rows
Example: Busy indicator in table rows

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

Object Display Components

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

  • Object status: a short text that represents the semantic status of an object
  • Object identifier: a short text that represents the key identifier of an object
  • Object number: a short text that represents the numeric (key) attribute of an object and its unit
  • Object marker: indicates the technical status of an object
From top to bottom: exemplary object status, object identifier, object number, and object marker
From top to bottom: exemplary object status, object identifier, object number, and object marker

Usage

Use the object display components if:

  • You need to display the semantic status of an object: negative, critical, positive, or neutral. Use the object status for this.
  • You want to display the key number of an object. In this case, use the object number and keep the default emphasized setting.
  • You need to display one or more numeric attributes of an object (for example, for objects you want to compare). Use the object number for this.
  • You want to indicate the key identifier of the object. Use the object identifier for this.
  • You want to display the technical state of an object (draft, unsaved changes, locked, favorite, flagged). Use the object marker for this, unless you want to display the status of the object in the business life cycle. In the latter case, consider using the object status instead.
  • You need to show that the current object instance is locked by another user. Use the object marker for this.

Do not use the object display components if:

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

Responsiveness

  • The object status wraps if it is longer than the available screen width.
  • The object identifier text wraps if the size of the screen becomes too small to display the entire text on one line.
  • The object number does not wrap or truncate. For large numbers, you need to consider using the appropriate formatting.
  • The object marker does not wrap or truncate. It comes with different display options: IconAndText, IconOnly and Text. On size S, the display option IconAndText only displays the icon due to lack of space. The other options are displayed as normal.

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

From top to bottom: Wrapping examples for the object status, object identifier, formatted object number, and two versions of the object marker
From top to bottom: Wrapping examples for the object status, object identifier, formatted object number, and two versions of the object marker

Components

Object Status

The object status is a short text that represents the semantic status of an object.

It consists of the following:

  • A semantically colored text indicating its status (property: text). We recommend using this semantically colored text-only option on its own. Check out the How to Use Semantic Colors / Industry-Specific Colors article for color options.
  • An optional icon (property: icon). If you need to have an icon, use one of the following:
     = positive/success
    = critical/warning
      = negative/error
    Note that there is no generic icon for “neutral” across industries. If you have a neutral object status, use the text-only version, a blank icon, or an icon that means neutral in the app’s specific business context.
Text-only object status and icon with text object status
Text-only object status and icon with text object status
  • An optional inverted visualization. Use the inverted object status if the information is crucial for the user’s actions and needs to stand out visually (for example, in table list items).
  • An optional link (property: active). If the object status is used as a link, a hover effect is shown on non-touch devices. Use this feature if the user needs additional information about the status (for example, in a popover). Note that if you use the object status as a combination of icon and text, there is no hover effect for the icon.
Inverted object status (left) and object status in hover state (right)
Inverted object status (left) and object status in hover state (right)
  • An optional larger font (CSS class: sapMObjectStatusLarge). Use this feature if the object status is important in the business context and needs to stand out visually in the page header (for example, key value facets in an object page).
Larger object status
Larger object status
Guidelines

  • In rare cases, an object can have two statuses at the same time. In this case, use the inverted text-only version for the most important status, and the normal text-only version (with an optional icon) for the less important status.
  • If you use the object status in a table, follow the corresponding sorting guidelines.
  • To prevent the text being read as a link, don’t use the blue “information state” for the object status.

Object Identifier

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

It has the following characteristics:

  • A title text (property: title)
  • An optional link (property: titleActive). In this case, the event can open the quick view of the object or a popover for example.
  • An optional additional descriptive text (property: text)
Guidelines

  • The object identifier should be easily readable (preferably the display text and not the ID).
  • If the object’s ID is necessary to distinguish between items that use the same title, it should appear as descriptive text below the title (property: text).

Normal object identifier, object identifier with link, and object identifier with descriptive text
Normal object identifier, object identifier with link, and object identifier with descriptive text

Object Number

The object number is a short text that represents the numeric (key) attribute of an object and its unit.

It consists of the following:

  • A colored text (property: number) based on the semantic color palette. Check out the How to Use Semantic Colors / Industry-Specific Colors article for more details.
  • An emphasized text which you can set to non-emphasized when you use it in the content area (property: emphasized).
  • An optional unit (property: unit).
Emphasized and non-emphasised object numbers
Emphasized and non-emphasised object numbers
Object number used as a semantic attribute (weight)
Object number used as a semantic attribute (weight)
  • An optional larger font (CSS class: sapMObjectNumberLarge). Use this feature if the object number is important in the business context and needs to stand out visually in the page header (for example, key value facets in an object page). Once the large font is applied, the object number can no longer be emphasized.
Guidelines

  • The object number can also be used to visualize other semantic numeric attributes. In this case, they are not emphasized unless they are the key attribute, such as a sum.
  • Emphasize the object number if it is used as a line item status in a table.

Emphasized and non-emphasized object numbers
Emphasized and non-emphasized object numbers

Object Marker

The object marker indicates the technical status of an object and can be interactive. It is enabled for the dynamic page layout, snapping header, object page header, upload collection, and object list item. The technical status can be represented as an icon, with an icon and text, or as text only, depending on the screen size.

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

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

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

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

Developer Hint
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. For details regarding draft handling, please see How to Display the Editing Status in the Draft Handling article.
Icons for draft, unsaved changes, locked, favorite, and flag (from left to right)
Icons for draft, unsaved changes, locked, favorite, and flag (from left to right)
Editing status examples
Editing status 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

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 micro 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 status.
  • You need to visually strengthen a current status.
  • You need to make different states comparable to each other at a higher level.
  • You want to show custom values as well as percentages.

Do not use the progress indicator if:

  • Visual feedback is needed for an ongoing operation. Use a busy indicator instead.
  • The progress is indeterminate. Use a busy indicator instead.
  • You want to display a single value in the form of a fillable shape or a group of shapes that describe their context. Use the status indicator instead.

Responsiveness

The progress indicator itself is not responsive. There is no visual difference between 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

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)

Enabled progress indicator
Enabled progress indicator
Disabled progress indicator
Disabled progress indicator

For usage in read-only forms or read-only tables, the progress indicator provides a “display” state. This state is optimized for reading environments. The default height is lower, and the bar color darker (property: displayOnly).

Progress indicator in display state
Progress indicator in display state

The progress indicator can visualize different value states that are represented by various theme-dependent semantic colors. The states are: normal, success, warning, error, and information (property: state).

For more information on how to use the different semantic states of the control, see How to Use Semantic Colors.

Value states can be combined with the “enabled” and “display” states.

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
Progress indicator in information state
Progress indicator in information 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 width property defines the width of the progress indicator. The height property 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 textDirection property is used for localiaztion (right-to-left languages).
  • The busy property sets the progress indicator to busy state.
  • The visible property shows or hides the progress indicator.
  • The tooltip property 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

Label

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

Every field needs a label. If you use one label for a group of fields, use a combined label and invisible text to label the single fields.

Label 'Name'
Label 'Name'

Usage

Use the label control if:

  • You need a label for a control.
  • Always use labels for form controls.

Do not use the label control if:

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

Required/Optional Fields

In edit mode, the label indicates whether an entry is mandatory (“required”) or optional.

If a field is required, an asterisk is shown after the label text. The asterisk is only visible in edit mode, and not in display mode.

In the image:

  1. Required, edit mode
  2. Required, display mode
  3. Optional, edit mode
  4. Optional, display mode
Information
To indicate that a field is required, set the required property to true.
Label for required and optional fields
Label for required and optional fields

Label Placement

In forms, you can place the label above the field value (recommended), or right-align the label next to the field value. For more information, see Label Alignment.

The position of a label can depend on the screen size. For example, the labels in a form can appear next to the input fields on larger screens, but move above the input fields when the screen size is reduced.

Labels next to the field and labels above the field (recommended)
Labels next to the field and labels above the field (recommended)

Styles

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

Wrapping

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

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

Developer Hint

The boolean wrapping property for the sap.m.Label control determines whether or not the text wraps .
Note: Only use this property in forms.

Labels in a form (edit and read-only modes, horizontal alignment)
Labels in a form (edit and read-only modes, horizontal alignment)

Hyphenation

The label control also supports hyphenation for wrapped texts (property: wrappingtype = Hyphenated). Switching on hyphenation activates it for all languages that have hyphenation support.

Guidelines

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

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:

  • 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

Analytical Card

The analytical card is used for data visualization. It consists of two areas – a header area (either a standard header or a KPI header) and a chart area with a visual representation of the data. The analytical card is a single object card and does not contain a footer area. It can only be used in the overview page (OVP). In the resizable card layout, users can show more content/insights by resizing the card.

Responsiveness

The analytical card has a uniform horizontal width of either 20 or 25 rem, depending on the screen size. The height is flexible.

The cards can be used in both the fixed and resizable card layouts. As a general recommendation for the fixed card layout, we recommend using a limited number of data points (up to 4) or series (up to 2). For the resizable card layout, you can add more data points for larger card sizes, but still try to keep the series limited (up to 2).

The VizFrame charts within the cards are fully responsive.

Header Area

You can use two header types for the analytical card, depending on the use case:

Standard Header

  • Title (mandatory): The title provides the most important information. We recommend using a single-line text, but you can also wrap the title to two lines.
  • Subtitle (optional): The subtitle can wrap to two lines, and gets truncated at the end of the second line. If the subtitle contains multiple qualifiers, separate them with comma. Do not repeat the chart title.
Standard header
Standard header

KPI Header

  • Title (mandatory): The title provides the most important information. We recommend using a single-line text, but you can also wrap the title to two lines.
  • Subtitle (mandatory): The subtitle can wrap to two lines, and gets truncated at the end of the second line. The unit of measure is shown at the end of the subtitle. We therefore 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.
  • 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). Use this element if the sorting information and the filters do not provide enough information to properly describe the value. This text truncates after one line.
    • Sorting information (mandatory): Describes the KPI/value.
    • Filters (optional): Can be modified to show meaningful texts.
    • Target and deviation (both mandatory). Can be relative or absolute values.
KPI header
KPI header
KPI header
KPI header

Types

8 chart types are currently supported by the analytical card:

Information
For additional information about the different chart types, as well as tips for choosing the correct chart type, see 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. You can choose between two line types: linear (default), and spline interpolation.

  • Avoid showing more than four lines on the same card.
  • When showing more than one line in the chart, do not use different units. All the lines should use the same unit, such as “EUR”.
  • You can use a line chart with both a time axis and another color dimension.

Line chart with time axis + color dimension
Line chart with time axis + color dimension

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 has an intrinsic order, such as age, ranges, or ratings (but excluding time).

Do not use the line chart if…

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

Note: For time series, we recommend using the time axis.

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 by the horizontal axis, another set is represented by 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.

Bubble charts are often used to facilitate the understanding of social, economic, medical, and scientific relationships.

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, 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 using 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 with only two dimensions.

Note: For time series, we recommend using the time axis.

Analytical card with bubble chart
Analytical card with bubble chart

Column Chart

Column charts are used to compare multiple values over time, or values that have 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 for 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 have an intrinsic order (such as age, range, or ranking).
  • You want to emphasize the values themselves, rather than the trend.

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 to emphasize the trend. In this case, use the line chart instead.

Note: For time series, we recommend using the time axis.

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 the variation of a 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.

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 value over time, or for a category that has an intrinsic order (such as age, range, or ranking).

The bullet chart supports primary values, secondary/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 have an intrinsic order.

Do not use the bullet chart if…

  • Your data does not have an intrinsic order.
  • You have only one series of data.
  • There is no data series that can 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 represents parts of a whole, where the whole is always 100%. The data is displayed in rings. Each ring represents a distinct data series.

The donut chart can display absolute values (default) or relative values (%). To make the values easier to read, we recommend showing a maximum of 2 decimal places.

  • If NumberOfFractionalDigits is not specified in the annotation, the default is to display a single decimal place.
  • If NumberOfFractionalDigits is specified in the annotation, the chart shows the values with the defined number of decimal places (0, 1, 2, 3, and so on).

We recommend using a maximum of four sections in the donut chart. If there are more than four sections in the chart, you can use an Other section, which merges several sections into one. The number of sections included in the Other section is mentioned in the legend item.

Use the donut chart if…

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

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

Note: If you are using donut chart in the resizable card layout, users will be able to see more of the sections that were grouped in the Other section as they increase the size of the card.

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 for a category that has an intrinsic order (such as age, range, or ranking).

You could also use a column chart or a line chart instead, 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 of the data shown in the line and columns is not logical.

Note: For time series, we recommend using the time axis.

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

Scatter Plot Chart

A scatter plot chart 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.

While the scatter plot chart can support different shapes, we recommend that you only use bubbles to make the chart easier to read.

If you need to increase or decrease the size of the bubbles, you can adjust the plotArea.markerSize property. The available range is from “4” to “32”. The default value of the bubbles is “10”.

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

Waterfall Chart

A waterfall chart is a form of data visualization that helps users to understand the cumulative effect of a sequence of positive or negative values.

This type of chart is helpful for a variety of different scenarios. For example, it could be used to visualize financial statements or changes in performance, or to navigate data on population, births and deaths.

In the fixed card layout, we recommend showing only the subtotal and total information (up to 4 columns).

The waterfall chart can be used with categorical axis, time axis and semantic colors.

Use the waterfall chart if…

  • You want to show intermediate totals along the way before showing the final cumulative total.
  • You want to show the net value, by breaking down the cumulative effect of positive and negative contributions.

Do not use the waterfall chart if…

  • You want to compare multiple values over time, or for values that have an intrinsic order (such as age). In this case, use the column chart instead.

Note: For time series, we recommend using the time axis. Note that totals and subtotals are not supported when using a time axis.

For more information, see Waterfall Chart.

Analytical card with waterfall chart
Analytical card with waterfall chart

Behavior and Interaction

The entire header area of the card is clickable. From there, the user can navigate to the specific app or view from which the card content originates. If you need to show detailed information about a specific data point, you can use single selection mode. In this case, it is up to the app developer to provide meaningful navigation. For example, clicking a section from the donut chart could lead to an object page that provides more information.

Analytical cards support 3 navigation modes. In all modes, clicking a blank area on the chart does not trigger any actions.

No navigation

If navigation is not defined in the identification annotation, clicking the header or the chart does not trigger any actions.

Data point navigation

If data point navigation is enabled, navigation within the chart is available only for data points. This is the default behavior: users can navigate from the header and from the individual data points.

For this header and chart navigation, set the navigation property to “dataPointNav”.

Header navigation

If you only need to offer header navigation without chart navigation, set the navigation property to “headerNav”.

Guidelines

Number of Data Points

There is no technical limitation on the number of data points, but be aware that too many data points can diminish the user experience. For example, if the card is only one column wide, and there is not enough space, the labels for the horizontal axis are displayed at 45°.

With the resizable card layout, you can load more data points when the card is wider than one column.

Chart Title

The chart title is always visible for each chart type. It describes the axes of the chart, and is constructed using the measures and dimensions of the chart. For example, Revenue by Quarter indicates that the y-axis represents the revenue, and the x-axis represents the quarters. The title is truncated at the end of the line.

Time Axis

You can use the different chart types with either a time axis or a category axis. We recommend using the time axis when the category items represent a time series. The time axis is more responsive and displays information in a more user-friendly manner than the category axis. Currently, the time axis is supported for the line, column, bubble, waterfall and combination charts.

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 taken care of automatically.
  • The physical spacing between the data points accurately represents the time scale, as opposed to being equidistant.

The analytical cards on the overview page automatically use the time axis if the following conditions are met:

  • The chart type is “Line”, “Bubble”, “Column”, “Waterfall” or “Combination”.
  • The chart is configured with only one dimension.
  • The data type of the dimension is either “datetime” or “edm.string”. If the data type is “edm.string”, it must contain the additional annotation in the OData metadata annotation (sap:semantics = “yearmonthday”).
  • If the chart type is “Bubble”, there must be exactly 2 measures.
  • If the chart type is “Combination”, there must be at least 2 measures.

Axis Title

The axis titles are always hidden, except in the bubble and scatter plot charts. Where the axis titles are hidden, use the chart title of the analytical card to describe the chart content. For example, Revenue by Quarter indicates that the y-axis represents the revenue, and the x-axis represents the quarters.

Axis Scaling

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

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

Axis Labels

Try to avoid displaying labels at 45°. Use abbreviations for time periods, 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 negativeBased on the defined threshold values, the color of each data point could be red, green, or orange. For more information, see colors.

Legend

Colors are assigned automatically and cannot be customized.

View Switch

You can use the view switch to offer the user different views of the data on one card. It can be used for filtering, sorting, or grouping (for example, 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

Message View

Intro

You can use the message view to display multiple transient messages. Unlike state messages, which always relate to a field on the UI, transient messages are related to an action.

Although the message view can be embedded within various controls, we recommend that you use it only within a dialog.

Message view
Message view

Usage

Use the message view if:

  • You want to display multiple transient messages within a disruptive dialog.

Do not use the message view if:

  • You want to display state messages. Instead, use the message popover.
  • You want to display a single transient message. Instead, use the message box.

Responsiveness

Size S (Smartphone)

The responsiveness of the message view is determined by the dialog container in which it is embedded.

Layout

Filtering

Multiple Message types – Filtering by Message Severity

If different types of message are available, users can filter messages by type (error, warning, success, and information) using the segmented buttons at the top of the message view.

Messages of different types can be filtered using the segmented buttons.
Messages of different types can be filtered using the segmented buttons.

One Message Type Only – Filtering Hidden

The filter bar is hidden if there is only one type of message (for example, only errors).

The filter bar is hidden if all messages are of the same type.
The filter bar is hidden if all messages are of the same type.

List

Short Description (1)

The short description comprises a simple and helpful text.

Subtitle (2)

The subtitle comprises a description that helps users to identify the object they are looking for.

Navigation to Second Page (3)

If there is a long text, the message popover automatically provides an arrow on the right for navigating to the message details.

Aggregating Messages (4)

You can aggregate messages by filling out the counter property of each list item.

Developer Hint
The message popover control only provides the counter property. The aggregation must be implemented by the app team.
Message view list items
Message view list items

Detail Page of the Message View

Users can filter messages by type (error, warning, success and information) using the segmented buttons on top of the message view.

The detail view has the following parts:

1. Back-end short text

2. Back-end long text

3. Optional link

Message view detail page
Message view detail page

Behavior and Interaction

Navigation to the Second Page of the Message View

If the backend contains a long text, the user can click the arrow/chevron on the right-hand side to view the full text in the second page of the message view.

Navigation to second page of the message view
Navigation to second page of the message view

Life Cycle

We recommend that messages no longer be displayed after the user closes the dialog (sap.m.MessageBox/sap.m.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

Message Popover

The message popover control can display multiple messages of different types in one list. For example, it might show several messages related to entries in a form, or messages triggered by a finalizing action, such as Save.

The message popover is used in conjunction with a technical message manager, which populates the message list. If an error occurs at a validation point, the corresponding message is added to message popover automatically, without interrupting the user.

Users can browse messages by type and navigate to the message details. In some cases, they can also jump directly from the message to the affected field on the UI.

Message popover
Message popover

When to Use

Use the message popover if:

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

Do not use the message popover if:

  • You need to interrupt the user. In this case, use a message box.
    (Typically, interrupting the user is only necessary for technical problems, such as network errors and connection issues.)

Components

Components of the message popover
Components of the message popover

(1) Filter bar
(2) Message short text
(3) Message subtitle
(4) Section/subsection on the UI
(5) Message button
(6) Navigation to message details
(7) Counter for aggregated messages

Filter Bar

Initially, the filter bar shows all the different message types in the list (1).

Segmented buttons at the top of the message popover allow the user to filter the messages by type (error, warning, success, and information).

List

Short Description

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

Subtitle

You can use the subtitle (3) to give your message an identifier. If the message relates to a specific field, show the label of the field where the error occurred. Based on the subtitle, the user should be able to identify the corresponding UI control on the UI (for example, the input field in a form).

Section/Subsection

Messages in the list are grouped by the section and subsection on the UI (4). This helps the user to find the part of the UI that triggered the message.

Navigation to Message Details

If message details are provided, the message popover automatically provides a chevron on the right-hand side for navigating to the message details page (6).

Aggregated Messages

If your app team wants to aggregate messages, they can use the counter property of each list item (7). Note that the message popover only provides the counter property. The aggregation itself must be implemented by the app team.

Message Button

If there are messages to display, the message button indicates the most critical message status in the list (5). For example, if the list contains an error message, the message button inherits the error icon and semantic color. If the most critical message in the list is a warning, the message button shows the warning icon and corresponding semantic color, and so on.

Message button types
Message button types

If there are no messages to display, there is no message button. In this case, the footer toolbar contains only the “normal” actions for the task.

Message Details

The message details page shows:

  • The message short text (1).
  • A more detailed message text to explain the issue and propose a solution (2).
  • An optional link to more information, such as app documentation (3).
Detail page of the message popover
Detail page of the message popover

Behavior and Interaction

When Does the Message Popover Open?

Form Field Validation

If one or more errors occur when the user fills out a form, the message button appears, indicating the message type of the most critical message. The message popover does not open automatically. For more information on the different validation points, see Form Field Validation.

Form field validation behavior
Form field validation behavior

Finalizing Actions

If the user activates a finalizing action (such as Create, Save, or Submit), the message popover opens automatically to inform the user about the errors on the UI that need to be resolved first.

Message popover triggered by a finalizing 'Save' action
Message popover triggered by a finalizing 'Save' action

Navigation to the Second Page

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

Navigation to the detail page of the message popover
Navigation to the detail page of the message popover

Navigation to the Relevant Field

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

Guidelines
Always add a navigation link, where possible.

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

Developer Hint
Set the navigation link with the activeTitlePress event. This allows users to click the message text in both the first and second page of the message popover.
Navigation from the message text to a field on the UI
Navigation from the message text to a field on the UI

Responsiveness

Size S (Smartphone)

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

Full screen message popover on a smartphone
Full screen message popover on a smartphone

Top Tips

  • Whenever possible, provide a navigation link from the message to the relevant field on the UI.
  • Use the message subtitle to indicate the field label.
  • In forms, also highlight the individual fields, and change their value state according to the type of message. For more information, see Form Field Validation.

Related Topics

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 with one action
Error message with one action
Error message with two actions
Error message 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 with 'OK' button
Warning message 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
Success message
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
Information message

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://question-mark
Title:  (such as “Approve”, “Reject”, or “Delete”)
Stretch: False (no full screen on all devices)

Button(s): Approve, Cancel

Confirmation message
Confirmation message

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://question-mark
Title:  Such as “Approve” or “Reject”
Stretch: False (no full screen on all devices)

Button(s): ApproveCancel

Confirmation message with note
Confirmation message with note

Confirmation for “Delete”

If the user clicks 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

Confirmation for 'Delete' action
Confirmation for 'Delete' action

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 options to display the text. Text can be displayed as:

  • Plain
  • Formatted
  • The original code format
Message details - Plain text
Message details - Plain text
Message details - Formatted text
Message details - Formatted text
Message details with code excerpt
Message details with code excerpt

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

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 select a single item from a large amount of data (for example, more than 200 items).
  • The user needs to find an object by searching for more than one attribute, such as an ID, city, and customer name. Use this control in combination with the autocomplete suggestion feature and value help option. For a small set of values (for example, fewer than 20 items), consider using the select control. Otherwise, use the combo box (for 20-200 items).

Do not use the input field if:

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

Responsiveness

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

Note that when tabular suggestions are used, the column headers stay sticky when scrolling within the suggestion list.

Size S (Smartphones)

Cozy mode:

When the user clicks 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
Tabular autocomplete suggestion with sticky header
Tabular autocomplete suggestion with sticky header

Size L (Desktops)

Compact mode:

The full table is shown by 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 implement format validation. If binding is used, validation is carried out by the model, but error handling must still be implemented on the UI side.

Text (default)

Input type text – Keyboard layout on a smartphone
Input type text – Keyboard layout on a smartphone

Number

Input type number – Keyboard layout on a smartphone
Input type number – Keyboard layout on a smartphone

Email

Input type email – Keyboard layout on a smartphone
Input type email – Keyboard layout on a smartphone

URL

Input type URL – Keyboard layout on a smartphone
Input type URL – Keyboard layout on a smartphone

Telephone Number

Input type telephone number – Keyboard layout on a smartphone
Input type telephone number – Keyboard layout on a smartphone

Password

Input type password – Keyboard layout on a smartphone
Input type password – Keyboard layout on a smartphone

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

Examples of input with different number masks
Examples of input with different number masks

Behavior and Interaction

Entering Text Using the Autocomplete Feature

Have a look at the interaction flow below:

Entering Text Using the Value Help Dialog

Have a look at the interaction flow below:

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

Styles

An input field can have the following styles. For more information, see UI Element States.

Input Field States
Input Field States

Properties

Value State and Value State Message

The input control offers the four value states listed below, for which you can show an additional value state text message when the focus is on the input field.

  1. Error
  2. Warning
  3. Success (no message is available for this state)
  4. Information

For more guidance on when to use which state, see How to Use Semantic Colors.

Input field in semantic colors with message box below
Input field in semantic colors with message box below

Enabled, Read-only and Disabled states

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

  1. Enabled: This is the default setting.
  2. Read-only: The input field isn’t shown, just the value. This is used in display-only forms.
  3. Disabled: The input field is shown with a visual indication that editing isn’t possible (for example, because the user isn’t authorized to make changes).
Input Field - Enabled
Input Field - Enabled
Input Field - Read only
Input Field - Read only
Input Field - Disabled
Input Field - Disabled

Required

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

Required input field
Required input field

Maximum Length

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

Placeholder

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

Placeholder
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. Instead of defining a fixed width, we recommend 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.

Text Alignment

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

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

Value Help

To help the user find the correct value, you can enable the value help option (propertyshowValueHelp). 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). 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.

Input Field with value help
Input Field with value help
Value help only
Value help only

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

Input Assistance

Intelligent systems can help users by recommending appropriate content or suggesting an action or input the user may “prefer”. The system assists the user by entering data or filtering data. Typical examples might be a search phrase suggestion, an appropriate form template, or a set of suggested default values for certain fields, based on the user input and interaction history.

For more information, see Designing Intelligent Systems – Input Assistance.

Autocomplete Suggestions

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

As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. The user can accept the autocompleted value by pressing ENTER. The autocomplete property is set by default if suggestions are available, but can also be switched off.

Warning
The typeahead input feature is not available on Android devices

Single Value with Autocomplete

Single-value autocomplete displays a list of suggestions with one left-aligned value. As a base for the aggregation suggestionItemssap.ui.core.Item is used.

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

See this 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 a customer and an ID.  As a base for the aggregation of suggestionItemssap.ui.core.ListItem is used.

The text property is displayed first, and is left-aligned. The additionalText property is right-aligned. The first text property is autocompleted in the input field.

Use the two-value autocomplete feature if you want to search by two attributes. This ensures that the search is carried out for both attributes.

See this 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. Use the tabular autocomplete feature if you need to display more than two attributes.

For input fields in a tabular view, we recommend using a maximum of 4 columns. Focus on columns that are really relevant for the use case.

To use the tabular autocomplete feature, use the suggestionColumns aggregation to define the columns and the correct responsive behavior for the pop-in. Define appropriate responsive behavior for sizes S and M. 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:

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.

See a live example of tabular autocomplete suggestions.

Tabular autocomplete
Tabular autocomplete

Grouping

You can group the items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

Input with grouped suggestions
Input with grouped suggestions
Input with grouped tabular suggestions
Input with grouped tabular suggestions

Guidelines

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

Maximum Columns

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

Maximum Length

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

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

Placeholder

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

Description

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

Width

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

Editable and Enabled States

Editable

Property settings: editable = true, enabled = true

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

Not Editable

Property settings: editable = false, enabled = true

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

Disabled

Property settings: editable = not relevant, enabled = false

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

Text Align

Align left if:

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

Align right if:

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

Value Help

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

Use this option in combination with the autocomplete suggestion feature.

When the user clicks 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.

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 fieldcombo boxmulti-combo box, and select controls.

Input field – New action
Input field – New action
Input field – Edit action
Input field – Edit action

Resources

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

Elements and Controls

Implementation

Message Strip

The message strip is a control that is used as an information bar. It contains information about an object or a status and can be embedded within the detail area of an object or page.

Usage

Use the message strip if:

  • You want to provide information within the detail area of an object.
  • You want to inform your user about a status of an object.
  • You want to warn your user about an issue.

Do not use the message strip if:

  • You want to display information within the object page header, within a control, in the master list, or above the page header.

Responsiveness

The message strip is fully responsive. Icons within the message strip are displayed to the left (custom icons) or right (Close action) of the message.  Text and links behave differently and wrap.

If you place the control within the detail area, it will always use 100% of the width and react to the responsiveness of the container.

Message strip on a smartphone (size S)
Message strip on a smartphone (size S)
Message strip on a desktop (size L)
Message strip on a desktop (size L)

Types

The following semantic types are available.

  • Information
  • Warning
  • Error
  • Success
Different semantic types and colors
Different semantic types and colors

Behavior and Interaction

Static behavior

The message strip acts as an information bar. If you want to display a status related to an object, keep the interaction static and do not show the Close button.

Static behavior used to display a status
Static behavior used to display a status

Interactive behavior

Clicking the Close button on the right side hides the message strip.

Interactive behavior with close function
Interactive behavior with close function

Properties

sap.m.MessageStrip is limited to the following properties:

  • Property:showIcon – Allows you to display an icon before the text
  • Property:customIcon – Allows you to display an icon from the icon library
  • Property:type – Changes the semantic color and the icon in front of the message strip
  • Property:text – Adds text to the control
  • Property:link – Adds a link
  • Property:showCloseButton – Adds a Close button

Resources

Elements and Controls

Implementation

Message View

Warning
We are still working on the image updates for this article. To see examples of the message view grouped by section/subsection, see the Message Popover article.

Intro

Containing features from the message popover control, the message view control gives you the flexibility to display multiple messages within SAP Fiori.

While message view can be embedded within multiple controls, we recommend that you use it only within a responsive popover or a dialog.

Message view
Message view

Usage

Use the message view if:

  • You want to display messages without using the message popover.
  • You want to display multiple messages.
  • You want to display multiple transient messages within a disruptive dialog.

Do not use the message view if:

Responsiveness

Size S (Smartphone)

The responsiveness of the message view is determined by the container in which it is embedded.

To display messages as popovers on desktop devices, or in full-screen mode on smartphones, we recommend that you use sap.m.ResponsivePopover as a container.

Layout

Filtering

Multiple Message types – Filtering by Message Severity

If different types of message are available, users can filter messages by type (error, warning, success, and information) using the segmented buttons at the top of the message view.

Messages of different types can be filtered using the segmented buttons
Messages of different types can be filtered using the segmented buttons

Grouping by section and subsections

Messages in the list are grouped by the section and (if relevant) subsection. This helps the user to find the field that triggered the message on the UI.

One Message Type Only – Filtering Hidden

If there is only one type of message (for example, only errors), the filter bar is hidden.

The filter bar is hidden if all messages are of the same type.
The filter bar is hidden if all messages are of the same type.

List

Short Description

The short description comprises a simple and helpful text.

Subtitle

The subtitle comprises a description that helps users to identify the object they are looking for.

Navigation to Second Page

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

Message view list items
Message view list items

Aggregating Messages

If desired, the app development team can aggregate messages by filling out the counter property of each list item. Note that the app team must implement this aggregation on their own as the message popover only provides the counter property.

Message view list aggregation
Message view list aggregation

Detail Page of Message View

Users can filter messages by type (error, warning, success and information) using the segmented buttons on top of the message view.

Message view detail page
Message view detail page

Behavior and Interaction

Navigation to the Second Page of the Message View

If the backend contains a long text, the user can click the arrow/chevron on the right-hand side to view the full text in the second page of the message view.

Navigation to second page of the message view
Navigation to second page of the message view

Message View Within a Dialog

Handling of Transient Messages

The message view also handles transient messages and is available within a dialog. Possessing the same interaction patterns as the message popover, this control helps the app development team to display messages more easily and consistently.

Transient message handling with the message view
Transient message handling with the message view

Life Cycle

We recommend that messages no longer be displayed after the user closes the dialog (sap.m.MessageBox/sap.m.Dialog).

Message View within a Responsive Popover

Handling Application-Specific Messages

The message view can be embedded in a responsive popover (sap.m.ResponsivePopover), for example, if you want to display multiple messages by clicking a button.

Due to the full screen behavior on smartphones (size S), we recommend that you use the responsive popover as a container.

Message view inside the sap.m.ResponsivePopover
Message view inside the sap.m.ResponsivePopover

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

Flexible Grid

The flexible grid control allows you to divide a layout into multiple columns and rows in which you can place UI elements. You can also customize the grid by aligning and arranging your elements to suit your content.

Since the flexible grid behaves responsively, it is suitable for both desktop and mobile devices. Depending on the available screen width, an optimized layout is loaded to ensure the best possible user experience on each device.

Example of a flexible grid layout
Example of a flexible grid layout
Information

Flexible grid uses the properties of the CSS grid. For more information,
see the CSS Grid Layout on the Mozilla Developer Network.

The grid is not fully supported by all browser platforms. It doesn’t work with Internet Explorer 11.

When to Use

The flexible grid can be used as an underlying layer for different types of page layouts, much like a template. You place elements such as cards or other SAP Fiori UI elements in the grid. This layout approach helps maintain one coherent experience within a page or across several pages.

Keep in mind that the elements placed in your grid are empty containers. Therefore, your grid layout is invisible until there is content in them to display.

Flexible grid with examples of cell areas
Flexible grid with examples of cell areas
Flexible grid with examples of Fiori UI elements placed in cell areas
Flexible grid with examples of Fiori UI elements placed in cell areas

The flexible grid can be used within different types of pages, such as the home page or other pages of an application. For an overview of the application page types, see the Explore page.

You can determine how you want to use the available space in your grid and how the content flows by adding breakpoints.

Some features and behaviors are configurable to enable the flexible grid for a variety of use cases. 

Flexible grid with example of space and content flow
Flexible grid with example of space and content flow
Flexible grid with example of space and content flow
Flexible grid with example of space and content flow

Use the flexible grid if:

  • You want to display your content in columns and rows so that it adapts flexibly to changes in the screen size.
  • You want to display your content in full-page layouts so that your content flows but stays aligned and spaced out evenly.
  • The focus of your layout is on flexibility and responsiveness, not on constraining the content to grid cells.
  • You want to include explicit or nested grid elements to have your elements or content adapt to any row or column size and to any breakpoints.
  • You want to have only one implementation for all devices.
  • You want to embed elements from another page into one of the columns.

Do not use the flexible grid if:

  • Your content is not appropriate for a card-like format, or for simple forms. For example, do not use the flexible grid for displaying a list or table that a user can edit or that needs to show a large number of items. Use a grid table instead.
  • You want to manage complex content, such as datasets that need to be extensively sorted, grouped, filtered, or edited. In this case, use a grid table instead.
  • You want to display a set of items on a grid. Consider using the grid list instead.
  • Your layout needs to be defined only by columns or only by rows, not both. Use a flex box instead.

Components

A  Column Elements can be placed in columns so they align horizontally in the layout.
B  Row Elements can be placed in rows so they align vertically in the layout.
C  Gutter – Column The gutters define the spacing between cells (space between columns).
D  Gutter – row The gutters define the spacing between cells (space between rows).
E  Margin – left The margins define the outer spacing of the grid layout (left, right, top, bottom).
F  Margin – bottom
G  Margin – right
H  Margin – top
I  Cell The cell is the smallest feature of the flexible grid. It is conceptually much like a table cell, and elements can be placed in a cell (or combination of cells) and aligned in columns and rows. The size of a cell depends on the width of a column and the height of a row. The width may differ from the height.
J  Cell area In this example, the elements are placed or mapped to 2 cells (aligned horizontally) and 2 cells (aligned vertically).

Flexible Grid Elements

You can place elements (SAP Fiori controls) in the flexible grid and then define the size of the elements by how they are laid out in the grid.

The order in which you add the elements determines how they appear in the layout.

Flexible grid elements with 9 columns and 5 rows
Flexible grid elements with 9 columns and 5 rows
Flexible grid elements with 9 columns and 5 rows
Flexible grid elements with 9 columns and 5 rows

Placement and Nesting

The grid layout can be used as a standalone, or inside other layout containers such as another page, a header, or a dialog.

The grid layout supports nesting, which allows you to place a flexible grid layout inside a grid element.

Flexible grid with a nested grid
Flexible grid with a nested grid
Flexible grid with a nested grid
Flexible grid with a nested grid

Behavior and Interaction

Layout Flexibility

You can use the flexible grid to define a layout for more than one page. This means you don’t need to define a template for each page.

Size of Elements in a Flexible Grid

Depending on the use case, you can assign specific sizes to a grid element to ensure that the content in the grid layout is displayed correctly.

Minimum and maximum size

If necessary, you can apply a minimum and/or maximum size to a grid element. For example, if the minimum width for a grid element is three columns, the space used by the element will never be less than three columns, even when the layout is resized.

Grid elements can also have a combination of specified minimum and maximum sizes (such as a range of sizes). However, you can only use whole (not half) columns or rows when referencing a size unit (for example, 2×3, 4×4).

Note: Keep in mind that the number of columns for a grid element should never be less than the minimum number of columns of the flexible grid layout in its smallest form factor.

Full-width elements

Grid elements can be defined to span the full width of the grid (using all the columns) for one or several rows in the grid layout.

Flexible grid and example of column widths
Flexible grid and example of column widths
Flexible grid and example of column widths
Flexible grid and example of column widths

Defining How the Content Fills the Space

You can define how the content fills the space of grid elements by adjusting the content to the height of the row. This can affect visual balance and consistency in the overall flexible grid layout. You can also choose to constrain content to the height of the elements (with a card control, for example).

Conversely, if the content doesn’t fill up all the space of the layout elements, you can include areas of white space (or empty space) to have “breathing” room in your layout.

Defining columns

Always use the full width of the layout elements, so that the content spans across the full width of the page or the width of the column.

Defining rows

When placing grid elements in rows, we recommend adding some white space (breathing space) between rows, especially if the content displayed in the elements is dense.

Note: You can choose whether to use the full height of the layout elements or only the desired space.

Flexible grid with example of how content adapts to the space in the layout
Flexible grid with example of how content adapts to the space in the layout
Flexible grid with example of how content adapts to the space in the layout
Flexible grid with example of how content adapts to the space in the layout

Responsiveness

You can enable your flexible grid to adapt to the size of the screen on a device (desktop, tablet, or phone), as well as to the display orientation or the available space on the screen.

Responsiveness is fully configurable by the developer. It is possible to create an adjustable layout with the flexible grid so that the content “breathes” (includes empty space). In this case, the columns adjust the content in the layout depending on the width of the overall grid.

You can define a new flexible grid at any breakpoint. With the flexible grid properties it is possible to define:

  • Columns, rows, and their sizes in the grid
  • Vertical and horizontal gaps, space between the grid elements
  • The flow algorithm when new elements are added to the grid.

The size of grid elements (or controls) is overridden when you specify how much space is used in the grid, or how many columns and rows the grid contains overall. If you specify the row or column from which an element starts, this overrides the automatically calculated position.

Flexible grid with responsiveness and element positioning
Flexible grid with responsiveness and element positioning
Flexible grid with responsiveness and shifted positioning
Flexible grid with responsiveness and shifted positioning

Row Height

There are only as many rows as needed by the grid elements. When resized, the grid adjusts the number of rows as content is added based on your predefined settings, such as the maximum number of rows and the minimum/maximum width of the grid.

Number of Columns

There are three options for defining the number of available columns in your flexible grid:

  • Predefined number of columns using breakpoints
    You can apply a predefined number of columns by using breakpoints based on the width of the screen. The width of the screen depends on the size of the device (S, M, L, and XL). When resizing the screen, the columns can “breathe” and every column width can be adjusted until a breakpoint is reached.
  • Flexible number of columns
    The number of columns is calculated based on the available width of the screen. When you resize the screen, the columns adjust in width to allow the content to adapt to the space on the page when new columns are added or removed.
  • Fixed number of columns and column width
    In this case, the number and size of columns is predefined. Therefore, depending on the width of the flexible grid, it might be necessary to show horizontal scroll bars. This approach is not responsive and should be avoided in layouts used on different form factors.

Columns and Breakpoints

Note: For reference only. For more information, see Responsive Spacing System.

 Screen  Breakpoints
S (phone) ≤ 599 px
M (Tablet) 600 – 1023 px
L (Desktop)  1024 – 1439 px
XL (Desktop) 1440 – 1919 px

Arranging Grid Elements

We recommend arranging flexible grid elements in a sequence so that the elements have a specific position in the layout.

Whether you add, remove, or rearrange elements, elements already in the grid will shift to the next or previous column (or row), depending on where they were initially positioned.

Content Flow

You can arrange layout elements so that the content displays or flows both horizontally and vertically in the flexible grid. If a column is set to auto-width and other columns have a fixed size, the auto-width column expands to the maximum width available, as defined by the overall grid width.

Flexible grid with auto-width column
Flexible grid with auto-width column

Here are two flow designs for the flexible grid:

Z-Flow (default)

Grid items are displayed in a sequence row-by-row (or Z shape-pattern), top-to-bottom. The reading order is left-to-right (when RTL is enabled, it is right-to-left).

ᴎ-Flow

Grid items are displayed in a column-by-column, top-to-bottom sequence (or N-shape pattern). The reading order is left-to-right (when RTL is enabled, it is right-to-left).

Resizing the Screen

When resizing the screen, the grid layout adapts to the available space, and the grid elements are automatically rearranged based on their position in the sequence. This allows you to apply the flexible grid to a variety of devices and use cases.

Developer Hint
The flexible grid is fully configurable by the developer. It is possible to let columns “breathe”, which means that the column widths grow/shrink depending on the grid size.
Example of responsiveness and size of columns
Example of responsiveness and size of columns
Example of responsiveness and resizing of columns
Example of responsiveness and resizing of columns

Implicit and Explicit Grid

The grid creates (implicit) rows and columns on its own when needed. For example, if a grid element is positioned in a row or column that is not explicitly sized, implicit rows or columns are created to hold it.

Developer Hint
Explicit grids are rows and columns defined with gridTemplateColumns and gridTemplateRows. Implicit rows or columns are defined with gridAutoColumns and gridAutoRows.
Flexible grid with explicit and implicit grids
Flexible grid with explicit and implicit grids

Top Tips

Include UI elements and controls that make sense in a flexible grid layout. Their content should adapt appropriately when the grid is resized, or the elements rearranged.

Include UI elements for which you might want to customize both the vertical and horizontal alignment.

If you want to include nested grids, consider the UX investment you’ll need to make to achieve the desired visual and structural result with your grid layout.

We don’t recommend using several nested grids, as it might result in an over-complicated UI layout. Also, the UI elements in your grid might not align at all with other UI elements of the grid as intended.

Properties

sap.ui.layout.cssgrid.CSSGrid

The following additional properties are available for the flexible grid:

  • The property width sets the width of the flexible grid.
  • The property gridTemplateColumns defines the number of columns in the flexible grid.
  • The property gridTemplateRows defines the number of rows in the flexible grid.
  • The property gridColumnGap sets the width of the gap (gutter) between columns.
  • The property gridRowGap sets the width of the gap (gutter) between rows.

Related Topics

Elements and Controls

Implementation

Infobar

The infobar is a type of toolbar that appears above a list or panel, and shows filter or selection settings:

  • Filter criteria: The infobar indicates the filter criteria that have been applied for a filter or contextual filter. Do not show the infobar if no filter is applied.
  • Selected items: In a multi-select dialog, the infobar shows the number of selected items.
The infobar is placed above the content and shows the applied filters
The infobar 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 infobar for a contextual filter.
Text is truncated on a small screen. The example shows an infobar for a contextual filter.

Types

There are three situations in which an infobar 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 infobar.

Infobar after a filter has been applied
Infobar 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.

Infobar after a contextual filter has been applied
Infobar after a contextual filter has been applied

Multiselection

If the user selects multiple items, the infobar shows the number of selected items. For more information, see select dialog.

Infobar after multiselection has been applied
Infobar after multiselection has been applied

Components

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

Infobar with optional Cancel icon
Infobar 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 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 infobar with a single filter shows the detailed filter selection.
Clicking the infobar with a single filter shows the detailed filter selection.
Clicking the infobar with multiple filters shows the filter categories.
Clicking the infobar with multiple filters shows the filter categories.

Icon Area

  • Cancel: The user clicks 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.

States

The infobar has two states – active and non-active (non-clickable). If set to non-active, the whole bar turns gray and the user cannot interact with it.

Infobar - Active state
Infobar - Active state
Infobar - Non-active state
Infobar - Non-active state

Properties

The contextual filter is not a separate control. If you want to build an infobar, you need to use the sap.m.toolbar control. To achieve the infobar 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

Multi-Input Field

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

Usage

Use the multi-input field if:

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

Do not use the multi-input field if:

  • You want the user to select one entry only. In this case, use the input field or combo box instead.
  • You want the user to select from a pre-defined set of options only. In this case, use the multi-combo box instead.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

Size S

  • Cozy mode.
  • When the user clicks the multi-input field, a new full screen dialog opens. After clicking the input field and typing, the suggestions can be selected. When the user makes a selection, the dialog closes and the token is displayed.
  • The user can review the tokens by swiping them to the left or right.
Suggestions on a smartphone (size S)
Suggestions 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

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

Size L

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

Types

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

Behavior and Interaction

Adding a Token

A token can be added using suggestions or value help. As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. The user can accept the autocompleted value by pressing ENTER. The autocomplete property is set by default if suggestions are available, but can also be switched off.

When an item is selected from the suggestions dropdown, the corresponding token is created, and the input field is ready for the next entry. Tokens are placed next to each other on one line.

Warning
The typeahead input feature is not available for Android devices.
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

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

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

Multi-input field - 'n More' label (desktop)
Multi-input field - 'n More' label (desktop)
Multi-input field - 'n More' label (phone)
Multi-input field - 'n More' label (phone)

If the length of the last selected token exceeds the width of the input field, a label [n] Item/s is shown when the field is not in focus.

Clicking the [n] Item/s label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its delete icon.

If there is only one token in the input field and its length exceeds the width of the input field, the text is truncated. Clicking the token opens a popover below the input field, in which the full text of the token is shown.

Multi-input field - '1 Item' case (desktop)
Multi-input field - '1 Item' case (desktop)
Multi-input field - 'n Items' label (desktop)
Multi-input field - 'n Items' label (desktop)

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

Left/right keyboard cursor
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

Filtering

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

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

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

Multi-input field - Default filtering, autocomplete in the input field is switched off
Multi-input field - Default filtering, autocomplete in the input field is switched off

Copying and Pasting Data from a Spreadsheet or Text File

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

Grouping

You can group the items items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

Multi-input with grouped suggestions
Multi-input with grouped suggestions
Multi-input with grouped tabular suggestions
Multi-input with grouped tabular suggestions

Due to a technical limitation, the group headers are not visible when clicking on the n More text. 

Group headers not shown when clicking on 'n More' items
Group headers not shown when clicking on 'n More' items

Styles

The following images show how the states of the multi-input field are styled.

Unselected
Unselected
Unselected with predefined placeholder
Unselected with predefined placeholder
Unselected on hover
Unselected on hover
In focus
In focus
Selected items shown as tokens
Selected items shown as tokens
Expanded multi-selection
Expanded multi-selection
Error
Error
Warning
Warning
Success
Success
Information
Information

For details on the different states, see UI Element States.

For more information on semantic colors for value states, see How to Use Semantic Colors.

Guidelines

  • Give the control a width that is appropriate for the range of values that are going to be entered. Try to avoid setting a fixed width on this control. Instead, embed it in a proper layout (such as a form, simple form, or grid layout) and work with the layout data property.
  • Provide meaningful labels for all input fields. Do not use the placeholder as a replacement for the label. The placeholder should only provide an additional hint.
  • The multi-input field can currently contain tokens and one free text value. If you allow only validated values, display an error or warning when the user tries to leave the field to indicate that the value entered is invalid, or remove the value.
  • If users try to select an item that has been selected before, we recommend setting an error state and providing a meaningful message.
Multi-input - Error state for an item that has already been selected
Multi-input - Error state for an item that has already been selected
  • You can use the layout options of the form to add the unit of measurement (UoM) after the multi-input control. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.
Developer Hint

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

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

Properties

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

Resources

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

Elements and Controls

Implementation

Multi-Combo Box

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

Usage

Use the multi-combo box if:

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

Do not use the multi-combo box if:

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

Responsiveness

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

Size S

 Filter bar with multi-combo box - Size S
Filter bar with multi-combo box - Size S
Option list in full screen - Size S
Option list in full screen - Size S

Size M

Filter bar with multi-combo box - Size M
Filter bar with multi-combo box - Size M

Size L

Filter bar with multi-combo box - Size L
Filter bar with multi-combo box - Size L

Also see the section on behavior for mobile devices.

Components

Input Field

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

Dropdown Trigger

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

Option List

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

Components of the multi-combo box
Components of the multi-combo box

Two-Column Layout

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

Multi-combo box with a two-column layout
Multi-combo box with a two-column layout

Behavior and Interaction

Select a Value

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

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

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

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

Developer Hint
With the showitems API, you can open the option list without having the dropdown arrow in a pressed state. Clicking the arrow again opens the full option list and sets it to pressed state. This way, you can show some items on focus and all items on click.

Input Field

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

Behavior - Sizes M and L
Behavior - Sizes M and L

Choose from Option List

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

Reviewing Tokens

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

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

Multi-combo box - 'n More' label
Multi-combo box - 'n More' label

If the length of the last selected token exceeds the width of the input field, a label [n] Item/s is shown when the field is not in focus.

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

If there is only one token in the input field and its length exceeds the width of the input field, the text is truncated. Clicking the token opens a popover below the input field, in which the full text of the token is shown.

Multi-combo box - '1 Item' case (desktop)
Multi-combo box - '1 Item' case (desktop)
Multi-combo box - 'n Items' label (Desktop)
Multi-combo box - 'n Items' label (Desktop)

Filtering the Option List

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

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

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

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

Warning
The typeahead input feature is not available for Android devices.
Multi-combo box - Default filtering and auto-complete
Multi-combo box - Default filtering and auto-complete

Grouping

Option list items can be grouped. Visually, the group header is a separate line above the items it groups. It does not currently provide an interaction of its own.

Multi-combo box - Grouping (desktop)
Multi-combo box - Grouping (desktop)
Multi-combo box - Grouping (mobile, Size S)
Multi-combo box - Grouping (mobile, Size S)

Behavior for Mobile Devices

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

Clicking the Arrow

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

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

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

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

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

Input Field on Collapsed List

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

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

Multiple Selected Items

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

Swiping to display tokens
Swiping to display tokens

Copying and Pasting Data from a Spreadsheet or Text File

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

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

Styles

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

Unselected
Unselected
Unselected with predefined placeholder
Unselected with predefined placeholder
Unselected on hover
Unselected on hover
On focus
On focus
Expanded
Expanded
Hover highlighting in list
Hover highlighting in list
Expanded selection
Expanded selection
Expanded multi-selection
Expanded multi-selection
Selected items shown as tokens
Selected items shown as tokens
Error
Error
Warning
Warning
Success
Success
Information
Information

For more information on how to use the different semantic states of the control, see How to Use Semantic Colors.

Guidelines

Label

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

Placeholder

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

Option List

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

Sorting

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

  • Logical: Sort items into a meaningful order. Group related options together and show the most common options first followed by less common options.
Logical multi-combo box
Logical multi-combo box
  • Alphabetical: Sort currencies, names, and so on into alphabetical order. We recommend this for lists with more than eight items.
Alphabetical multi-combo box
Alphabetical multi-combo box
  • Numeric: Sort numeric values into a sequential order with the lowest number first.
Numeric multi-combo box
Numeric multi-combo box
  • Chronological: Sort time-related information into chronological order with the most recent first (if applicable).
Chronological multi-combo box
Chronological multi-combo box

Width

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

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

Unit of Measurement

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

Developer Hint

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

Multi-Combo Box in a Filter Scenario

The multi-combo box can serve as a filter. For example, if the multi-combo box is offered in a table toolbar, and is empty (no tokens selected), the table shows all items. If the user selects picks something in the multi-combo box, the table shows only the matching items.

In addition, users can select or deselect all items from the option list in the multi-combo box using the keyboard. This is done by focusing somewhere in the list and pressing Ctrl+A / Ctrl+Shift+A.

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

Color Palette

You can use the color palette to let users choose a color from a predefined set of colors. The colors are fixed and do not change with the theme.

Color palette
Color palette

Usage

Use the color palette if:

  • The user needs to select one color from a predefined set of colors.
  • The color set contains between 2 and 15 predefined colors.
  • There is no need to offer additional colors.

Do not use the color palette if:

Responsiveness

The color palette supports cozy and compact content densities.

Size S
Size S
Size M
Size M
Size L
Size L

Components

  • A link to select the default color (optional).
  • The color palette, consisting of 2 to 15 color buttons.
  • Recent colors (optional). Users can see the last 5 colors they have recently picked. This function helps users to select colors that they have already chosen from the color picker. By default, this feature is visible.
Color palette with all optional features
Color palette with all optional features
Color palette with 15 colors and just one recent color
Color palette with 15 colors and just one recent color

Behavior and Interaction

Users can select a color with the left mouse button, the tap gesture, or by pressing SPACE or ENTER on a keyboard. The selected color is not indicated in the control itself.

Hovering over a color provides a visual feedback.

To navigate between different colors on a keyboard, use the arrow keys.

Visual feedback on hover
Visual feedback on hover

Guidelines

  • Show the selected color in another place. The color palette does not visualize the selected color.
  • Label the color palette.
  • If you do not want to show the color palette in-place, consider the color palette popover instead.

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 / Simple Form

Information
This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

Intro

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 labelsinput fieldscheckboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two 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).

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 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 and simple 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 / breakpointLbreakpointXL. 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 and simple 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 and simple 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 and simple 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.

Size XL

Like the form and the simple 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 L and XL
Form in size L and XL
Developer Hint
For forms and simple 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)

Column Layout

If you use the default form settings, each form group displays in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right of the screen.

To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns (layout: ColumnLayout).

You can use this option to distribute the content for up to two form groups. As soon as there are more than two form groups, the display reverts to the default layout (one column per form group).

The examples below show how forms with one and two form groups display with and without layout balancing.

One form group with default arrangement
One form group with default arrangement
One form group with balanced column layout
One form group with balanced column layout
Two form groups with default arrangement
Two form groups with default arrangement
Two form groups with balanced column layout
Two form groups with balanced 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.

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.

Label Alignment

  • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
  • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
Information
The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

Unit of Measurement

You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

Unit of Measurement
Unit of Measurement

Amount Alignment

When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

Label

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

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

Input Assistance

Intelligent systems can help users by recommending appropriate content or suggesting an action or input the user may “prefer”. The system assists the user by entering data or filtering data. Typical examples might be a search phrase suggestion, an appropriate form template, or a set of suggested default values for certain fields, based on the user input and interaction history.

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

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

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 to 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 datasets 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
Don't: Display a mix of both actual and percentage values
Don't: Display a mix of both actual and percentage values

Values

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

Display of positive and negative measures
Display of positive and negative measures

Semantic Colors

The interactive bar chart supports semantic colors that are shown as color markers. Since interactive charts are used to filter content visually, these markers give users even greater clarity when evaluating the information.

Use semantic colors when you want to make users aware of critical thresholds or categories.

Example of a semantic color
Example of a semantic color

Behavior and Interaction

Selecting and deselecting a bar is toggle-like behavior – if the user clicks  a selected bar, it becomes deselected, and vice versa. By default, the interactive bar chart supports multiple selections – the user can select more than 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 a maximum of three filter values with their corresponding measures.

In general:

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

Filter by categorical data
Filter by categorical data
 Filter large sets of data by time period
Filter large sets of data by time period
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 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 datasets 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 a different position relative to the labels, such as above or below them.

Do
Do: Align both areas (visualization and filter label and measure) and show them at the same height
Do: Align both areas (visualization and filter label and measure) and show them at the same height
Don't
Don't: Leave both areas (visualization and filter label and measure) unaligned
Don't: Leave both areas (visualization and filter label and measure) unaligned

Values

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

Semantic Colors

The interactive donut chart supports semantic colors that are shown as color markers. Since interactive charts are used to filter content visually, these markers give users even greater clarity when evaluating the information.

Use semantic colors when you want to make users aware of critical thresholds or categories.

Example of semantic colors
Example of semantic colors

Behavior and Interaction

Selecting and deselecting a section resembles toggle-like behavior. If the user clicks 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:

  • 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

Single Planning Calendar

The single planning calendar is a scheduling control that displays the calendar of a single person or resource over a day, work week, or week. Users can view appointments, create new appointments, and delete appointments.

Single planning calendar
Single planning calendar

Usage

Use the single planning calendar if:

  • You want to enable users to schedule or monitor the calendar of a single person or resource.
  • You want to offer multiple calendar views (day, work week, week).

Do not use the single planning calendar if:

  • You want to compare objects of the same type over a given period (for example, appointments for multiple persons or resources). In this case, use the planning calendar.
  • The main use case is to schedule all-day appointments, and you don’t need to see an hour axis. In this case, use the planning calendar.
  • You need a complex graphical representation or planning application involving activities, resources, hierarchical project structures, relationships, and so on. In this case, use the Gantt chart.

Responsiveness

The single planning calendar is responsive and supports the cozy and compact density modes.

Overflow Behavior

On smaller screens, the custom toolbar utilizes the overflow behavior of the standard SAP Fiori toolbar.

If the available actions do not all fit into the available space on the toolbar, an overflow menu button appears on the right of the toolbar. The rightmost actions move into the overflow menu first.

Single planning calendar - Size L
Single planning calendar - Size L
Single planning calendar - Size M
Single planning calendar - Size M
Single planning calendar - Size S
Single planning calendar - Size S

Components

The single planning calendar consists of the following components:

  1. Header
  2. Toolbar
  3. View switch
  4. Navigation
  5. Date strip
  6. All-day appointment
  7. Timeline
  8. Appointment
  9. Calendar grid
  10. Now marker
Components of the single planning calendar
Components of the single planning calendar
Developer Hint
To prevent waiting time, app developers should load the sap.ui.unified library.

1. Header

The header contains the toolbar and the navigation.

2. Toolbar

The toolbar consists of the calendar title (optional) and the toolbar actions, including a default view switch. You can add other app-specific actions that are relevant for your use case (such as creating an appointment, search, filter, settings, showing the calendar legend, and so on). Always place actions that affect the entire calendar in the toolbar.

3. View switch

The view switch allows the user to switch between different time intervals. The default views are day, work week, week, and month. The app developer can choose which views to include, depending on the use case.

In the month view, all appointments for the respective day have the same width and height. Each grid cell can hold 4 appointments in compact mode and 3 appointments in cozy mode. The remaining appointments can be accessed with a # More link. In month view, all-day appointments look and behave like regular appointments.

Month view
Month view

You can also create custom views by setting a different number of visible columns in the grid. We only recommend doing this if your use case really requires it. You must also ensure that any custom views are responsive. For anything over 7 days, provide an alternative view for size S.

Custom view 10 days - size L
Custom view 10 days - size L
Custom view 3 days - size S
Custom view 3 days - size S
Developer Hint
If no view is set by the application developer, the single planning calendar renders the week view. If the application developer sets only the day view, the week view is not visible.

4. Navigation

The navigation area contains back and forward arrows, the Today button, a date interval link, and the date strip. Clicking the Today button takes the user to the period containing the current day.

5. Date strip

The date strip is the horizontal axis of the calendar grid, showing the currently visible day or days. Non-working days are a darker color.

6. All-day appointment

All-day appointments are appointments that take up 24 hours. They are located in a dedicated area below the date strip and above the first hour of the timeline.

The option to create all-day appointments must be added at application level. Consider using a switch or checkbox that automatically sets the start and end time of the appointment to 00:00. We recommend reflecting this in the UI for creating the appointment as well. For example, offer a date picker instead of a date/time picker for selecting the start and end of the appointment (as shown in the sample dialog).

There is no limit of the height of the all-day appointments area. However, if your use case involves a lot of all-day appointments (and their area takes up most of the screen), consider using the planning calendar instead.

7. Timeline

The timeline is the vertical axis of the calendar grid, showing the hours.

8. Appointment

Each appointment can have an icon or image, a title, and a subtitle. If there is not enough horizontal space for the text, it is truncated. If an appointment has an icon, the icon remains visible as long as there is space for it, even if that does not leave enough space for the title. If there is not enough vertical space, the subtitle is not shown.

Appointments vary in height, depending on their duration, and in width, depending on how many appointments take place simultaneously. The minimum height of an appointment corresponds to a 30-minute appointment.

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

9. Calendar grid

The calendar contains the appointments and all-day appointments, and is controlled by the currently selected view. Non-working days have a darker background color in the calendar grid.

10. Now marker

The now marker is a horizontal line through the calendar grid, which indicates the current time. The current time is visible on the timeline. If the current time falls within 15 minutes of a full hour, it replaces the full hour.

Appointment structure
Appointment structure
Now marker - Current time replaces the full hour
Now marker - Current time replaces the full hour

Behavior and Interaction

Date Picker

The visible period is indicated with the date interval link in the navigation. Clicking the link opens a date picker, which helps the user to navigate quickly to a specific day or week.

Creating an Appointment

We recommend offering a Create action in the toolbar.

The UI for creating the appointment must be implemented at app level. The control provides only the underlying functionality for creating appointments. For most use cases, a dialog works best and is recommended (see sample dialog below).

Viewing Appointment Details

The UI for viewing appointment details must be implemented at app level. The control provides only the underlying functionality for displaying appointment details. We recommend using a popover to keep the context for the user (see sample popover below).

Working Hours

You can opt to set working hours in the single planning calendar (properties: startHourendHour). The non-working hours then have a different background and can be hidden (property: fullDay). You can also give the user the option to toggle between working and non-working hours. We recommend offering a toggle button in the toolbar (the button must be added by the app team).

Sticky Header

To keep the context when the user scrolls down the calendar, the header area of the single planning calendar can remain fixed at the top of the screen (property: stickyMode).

At app level, you can choose to have the entire header area sticky (value: All) or only the Navigation area (value: NavBarAndColHeaders).

Drag and drop

You can enable drag and drop for moving appointments (property: enableAppointmentDragAndDrop). Moving an appointment changes its start and end times (for example, if an appointment is scheduled from 1:00-2:00 PM, the user can drag it and change the time slot to 2:00-3:00 PM). When dragged, the appointment is shown as a ghost element on the mouse cursor. A placeholder indicates the target drop area.

Appointments can also be dragged from or to the area for all-day appointments. When the user drags an all-day appointment to the planning area, a placeholder shows the duration of the appointment after dropping (default = 1 hour). Similarly, dragging a regular appointment to the all-day appointments area transforms it into an all-day appointment (default = 1 day).

For desktop devices, you can also enable the following options:

  • Allow users to create new appointments by clicking, dragging, and releasing on an empty space in the content area (property: enableAppointmentsCreate).
  • Allow users to change the duration of an appointment by clicking and dragging one side of the appointment (property: enableAppointmentsResize).
Drag and drop
Drag and drop
Drag and drop into the all-day appointments area
Drag and drop into the all-day appointments area
Drag and drop from the all-day appointments area
Drag and drop from the all-day appointments area

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 to 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 datasets 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
Don't: Display a mix of both actual and percentage values
Don't: Display a mix of both actual and percentage values

Values

The interactive line chart can display positive, negative and mixed (positive and negative) 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.

Example: Positive and negative values
Example: Positive and negative values

Semantic Colors

The interactive line chart supports semantic colors, which are shown as color dots. Since interactive charts are used to filter content visually, these colors give users even greater clarity when evaluating the information.

Use semantic colors when you want to make users aware of critical thresholds or categories.

Example: Showing a critical line chart data point using a semantic color
Example: Showing a critical line chart data point using a semantic color

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 first or last six data points (such as last six days, last six months, and so on).

In general:

  • 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

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.

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 the list in a list-detail layout (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

Placement Types

The placement type defines how the popover will be positioned on the screen in relation to its trigger. The default placement is “Right”: the popover appears to the right of the object it relates to.

If you set the placement type to “Auto”, the position of the popover in relation to the reference control is determined automatically, depending on the available space.

Popover with default placement type - Right
Popover with default placement type - Right
Developer Hint
More information on the different placement types can be found here.

Modal Mode

The popover in modal mode opens in a modal window, which blocks the whole screen and attracts the user’s attention.

Use the modal mode only if you want to prompt the user to make a decision or confirm an action. Ensure that the user can close the popover, either by offering an action button in the footer or a Close button in the header.

Popover – Modal
Popover – Modal

Behavior and Interaction

Opening a Popover

The user opens a popover by clicking 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 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 scrollbar 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

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

The process flow enables different layout forms within the nodes:

  • The default layout contains fixed sections that can easily be filled with content.
  • The freestyle layout comprises an empty container that can be filled with different controls.

Default (Fixed) 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.

Freestyle Layout

The freestyle layout gives you the most freedom within the borders of each node. Inside this empty container, you can structure your content as your use case requires. Of course, you still need to conform to the guidelines for each control you use in your layout. The next sections show two examples of freestyle layouts with texts and images.

If text is the main focus of a node, we recommend using the “dog ear” visualization (property FoldedCorners = true, see Styles section for further details). If an image is the most notable content of a node, we advise against using the “dog ear” visualization.

Regardless of the controls you use inside the nodes, ensure that users can easily identify the item or meaning behind a node without having to click it. Users should only have to click to retrieve additional information or to perform an action, but not to identify an item. An exception to this rule is the lowest zoom level, which only shows the most basic information.

What should be displayed at the lowest zoom (level 4) depends on the context and use case of your application. If an image is the centerpiece of the node, a down-sampled version of this image can help users to identify each individual node. In other instances, an icon might be more appropriate to show the status of a node or hint at its content. In both cases, it is mandatory for applications to supply an icon (such as  to indicate that the object is in process, or   to show that the item contains textual information). You can also use status icons with semantic colors if they support the use case.

You can offer actions on the popover or quick view that is triggered to show additional information. If no additional information is required, you can also use the node’s click event to trigger an action sheet. However, use this latter option with caution; for most use cases, you will need to show additional information, especially at the lowest zoom level.

Freestyle Example: Text

If you need to display text inside a node, you can use the built-in click event to show a popover with the full text and any additional actions. While zooming out, less and less text is shown until the smallest zoom level is reached. Since text cannot be previewed in such a small container, use the icon   to indicate that the item contains textual information.

Layout – Freestyle – Text 01
Layout – Freestyle – Text 01
Layout – Freestyle – Text 02
Layout – Freestyle – Text 02
Layout – Freestyle – Text 03
Layout – Freestyle – Text 03
Layout – Freestyle – Text 04
Layout – Freestyle – Text 04

Freestyle Example: Image

The following examples show how images can be displayed inside the process flow nodes – in this case to represent an employee. Additional information, such as the employee’s profile and contact information, can be shown in a quick view. As the node gets smaller with each zoom level, some information needs to be omitted. On the lowest zoom level, only the image is shown.

Layout – Freestyle – Image 01
Layout – Freestyle – Image 01
Layout – Freestyle – Image 02
Layout – Freestyle – Image 02
Layout – Freestyle – Image 03
Layout – Freestyle – Image 03
Layout – Freestyle – Image 04
Layout – Freestyle – Image 04

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

Highlighted Path

The “highlighted path” feature 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 is dimmed.

Attention: Do not combine a highlighted path with a selected path. When you set one path type, make sure that the other is deactivated.

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

Editing

If users can edit a node’s content, offer an Edit button. Place the button on whatever is triggered when the user clicks a node (action sheet, popover, quick view). The editing itself can be handled in a small dialog. The information structure depends on the controls used inside the node. Usually, a form and/or text areas will cover most use cases.

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 single 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.
Use the following format to describe the stack and the number of nodes it contains: <Object Type> (<Counter>). For example, Invoices (8) or Sales Orders (42).

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 may lead to usability issues. Handle every action or interaction via a popover and/or navigation to a subsequent page.

UI Texts

Use a noun to describe the process phase.
Example: Accounting

If the process and a business object have the same name, add Processing to the process name.
Example: Order Processing (in this case, “Order” is used for the business object)

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

Radio Button

Radio buttons provide users with a set of mutually exclusive options. They allow a user to select only one option from two or more choices. Each option is represented by a radio button. Consequently, radio buttons only work in groups.

Usage

Use the radio button if:

  • You need to help users choose quickly between at least two clearly different choices.

Do not use the radio button if:

  • You need to offer the user the option of multiple selection. In this case, use checkboxes instead because radio buttons are for single-selection contexts only.
  • You want to allow the user to select list items. Instead, let the user tab the list item to make a single selection (consider a message toast for confirmation) and provide checkboxes to select multiple list items.
  • The default option is recommended for most users in most situations. In this case, consider a dropdown list instead, which uses less space by not showing all options straightaway.
  • You need to present more than 8 options. Use a dropdown box or list view.
  • In special cases, there are only two mutually exclusive options. Combine them into a single checkbox or toggle switch. For example, use a checkbox for “I agree” (for example, to terms and conditions) instead of two radio buttons for “I agree” and “I don’t agree”.
  • The options are numbers with fixed steps. Use a slider control.

Responsiveness

The radio button group control is not responsive. A horizontal radio button group should be displayed as a vertical group on smartphones because a horizontal group should never break into two lines.

Also note that the control does not handle long labels in horizontal groups. Such labels do not break and are not truncated. Therefore, check label lengths and padding in horizontal groups on desktop and tablets.

A horizontal radio button group does not match the size of mobile phone screens
A horizontal radio button group does not match the size of mobile phone screens
On smartphones, a horizontal group should always break into a vertical button group
On smartphones, a horizontal group should always break into a vertical button group

Behavior and Interaction

Activation

The user taps a radio button to activate the related option. Note that tapping an activated option does not deactivate it, but tapping a different option transfers activation to that option. Therefore, a user can select only one option from a group of radio buttons.

A group of radio buttons behaves like a single control: Using the tab key sets the focus directly on the selected option. Users can cycle through the group using the arrow keys.

Styles

States

A radio button can have different states that affect its appearance:

  • Control states, such as “enabled” or “read only”
  • Value states, such as “error” or “warning”, which are indicated using semantic colors
  • Visual states, such as “regular” or “hover”
  • Additional states, such as “selected”

For details on the different states, see UI Element States.

For more information on semantic colors for value states, see How to Use Semantic Colors.

Radio button interaction states
Radio button interaction states

Column Attribute

The radio button attributes also have a set arrangement so that you do not have to implement them for every single control. The column attribute adds or removes n-columns to a set of radio buttons.

Three columns – The example shows background color settings
Three columns – The example shows background color settings
One column – The example shows a customer survey
One column – The example shows a customer survey

Guidelines

The radio button control serves the purpose of exclusive selection and adds clarity and weight to very important options in your app. Use radio buttons when the options being presented are important enough to occupy more screen space. They should only be used if the user needs to see all available options instantly and side by side. Radio buttons draw more attention to the options as they emphasize all options equally.

Labeling

A label to indicate the option is mandatory for each radio button. Limit the radio button’s label to a single line.

Sorting

List the options in a logical order, such as lowest to highest risk, simplest to most complex operation, or most to least likely to be selected.

Alphabetical ordering is less recommended as it is language-dependent and therefore not localizable.

Aligning

Try to align radio buttons vertically instead of horizontally, especially for long labels. Horizontal alignment is harder to read and localize. Consider horizontal alignment in cases of one-word labels, such as in the background color settings example above.

In forms, always align radio buttons vertically instead of horizontally as the length of the labels may vary for different languages.

Do not put two radio button groups right next to each other as it is difficult to determine which buttons belong to which group. Use group labels and padding to separate them.

Offering “No Choice”

If the user is also able to select none of the options, be sure to add this option to the control as well (as this option is generally not offered in the control). Add a radio button that offers None or Does not apply.

Default State

Because radio buttons do not generally offer “no choice”, the app should show the less risky option (most likely the first option in the group) as preselected by default.

Exceptional Case: No Preselection by Default

In rare cases, preselection might result in incorrect inputs or assumptions. One such example is gender selection in a form. In this case, you should offer no preselection and decide whether a user input is mandatory or not depending on the use case.

If a choice is mandatory, set an error state if validation proves that a user did not select an option.

Offer no selection by default in this case of gender selection because a preselection might be misleading
Offer no selection by default in this case of gender selection because a preselection might be misleading

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

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 for a master-detail scenario using the flexible column layout and in popovers or dialogs. In certain use cases, they can also be used in the dynamic page layout.

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 first column of the flexible column layout).
  • Selecting one or more items out of a set of hierarchically structured items is a main use case.
  • The hierarchy has a restricted number of levels (up to about 12, depending on the content) 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 very 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 around 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 wrap to ensure that the tree adapts to the new size.

In addition, the tree changes the indentation per level dynamically when the user expands a node, based on number of levels currently showing.

Tree displaying 2 levels
Tree displaying 2 levels
Tree displaying 3 levels
Tree displaying 3 levels
Tree displaying 4 levels
Tree displaying 4 levels

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)
  • text
  • A counter (optional)
  • Additional buttons with actions such as Edit, Navigate, or Delete (optional)

If additional controls are needed, use a custom tree item. The custom tree item allows you to use any combination of controls inside the tree.

Standard tree item
Standard tree item

Behavior and Interaction (incl. Gestures)

Tree Level

Scrolling

The height of the tree is defined by the number of items it contains. It does not have its own scroll container, but is scrolled together with the app.

Same tree, with different expand state
Same tree, with different expand state

When the user scrolls, the title and the filter infobar can stick to the top of the surrounding layout container (sap.m.Tree, property: sticky).

Information
The “sticky” feature comes with some limitations:

  • It is not available on all browsers. In non-supporting browsers, the corresponding areas are not fixed on top of the surrounding layout container while scrolling.
  • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the table is placed within the object page.
  • If focus is set to a sticky area, the tree is automatically scrolled to top.

Sticky title
Sticky title

Selection Modes

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.

Multiple selection: 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 of the others. The Shift key can be used to select a range (sap.m.ListMode.MultiSelect).

Developer Hint
In multiple selection mode, users can (de)select all items using the shortcut CTRL+A. This only affects items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded (for example, items added via lazy loading with growingScrollToLoad). This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

Also note that CTRL+A only (de)selects items within expanded nodes.

To process all items, listen to the selectionChange event and to its flag selectAll. This indicates whether CTRL+A was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

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

Line Item Level

Expandable and Collapsible Nodes

An Expand/Collapse button is provided automatically for each node.

Expand/collapse button
Expand/collapse button

Highlight an Item

To highlight an item, use the “highlight” indicator (sap.m.TreeItemBase, properties: highlight).

Highlighted item
Highlighted item

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 the line triggers the navigation event. However, clicking 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

Indicate Navigated Item

When multi-selection is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case only (multi-selection tree with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.TreeItemBase, property: navigated).

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

Context Menu

You can attach a context menu (sap.m.Menu) to a tree. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

The context menu can be triggered for the tree or per item.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or SHIFT+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a tree is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Tree - context menu
Tree - context menu

Drag and Drop

One or several items can be repositioned within a tree or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop
Whole item as drop target
Whole item as drop target

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.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the tree. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning
The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

  • The number of rows in the table
  • The number of displayed columns
  • The complexity of the cell content (for example, simple text vs. complex charts)
  • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
  • The browser being used

Title

Use a title only if the title of the tree is not indicated in the surrounding area. If needed, implement the title text by adding a title to a toolbar. Place the toolbar above the tree.

Do not use a title if it simply repeats text that is already above the tree. For example:

  • Beverages tree is the only control on a tab labeled Beverages.
  • A section or subsection on an object page contains only one tree.

Use a title if you need the item count, toolbar, or variant management. To avoid repeating text, feel free to use generic text as a title, such as Items.
Exception: If the surrounding area contains the title, and both the item count and toolbar can be added to the surrounding area, no additional title is needed.
Example: An object page (sub-)section contains only one tree. In this case, add the item count and the table toolbar to the (sub-)section header.

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 only leaves (for example, if nodes are mainly used for categorization).

Remove the item count in the title if there are zero items.

If possible, keep the toolbar sticky (sap.m.Tree, property: sticky).

Developer Hint
Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the tree.

If you don’t use a title (for example, to avoid repetition), make sure that the tree is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

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

 

Examples:

  • If a tree is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the tree with data.
  • If a tree is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    No filters set. To start, enter your search and filter settings and run the search.
  • If a tree is used together with a filter bar and the filter does not return results, use the following text:
    No items found. Check the search and filter settings.

Adapt the texts above if:

  • The text is not precise enough for your use case (for example, no search is offered, only the search is offered).
  • You are using the live search (no Go button in the filter bar). In this case, leave out “run the search”.
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).
Provide meaningful instructions within an empty tree
Provide meaningful instructions within an empty tree

Highlighting Items

To show that an item needs attention, you can display a highlight indicator in front of the item. The highlight indicator can be used to indicate:

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors.

(sap.m.ListItemBase, 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 contains an error, for example within the global edit flow, add the string (Contains errors) to the text of the item and highlight the row accordingly.

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: AddCollapse AllExpand 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.

Add Items

For adding items, place an Add or Create text button on the toolbar.

  • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
  • Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the tree or node:

  • If nothing is selected, add the new item to the root.
  • If a single node is selected, add the new item to the selected node.
  • If a single leaf is selected, add the new item as a child of this leaf. The original selected item becomes a node.

If your tree doesn’t support adding items to the root, selected node, or selected leaf, disable Create or Add for the corresponding levels.

Disable Create or Add if more than one item is selected.

For more details, see guidelines for managing objects (including subarticles).

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that tells the user how many items will be affected. Let users choose whether to apply the action anyway or cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element – States.

If the action was applied and the items are still available, keep them selected.

Message for an action that applies to a part of a selection
Message for an action that applies to a part of a selection

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.

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. Also, because there is no generic keyboard interaction, drag and drop isn’t accessible. Moreover, drag and drop is not available on all browsers. For these reasons, offer drag and drop only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.

Use drag and drop only in addition to existing visible UI elements
Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within a tree, use the following options:

  • For dropping items as a child, use whole nodes as drop targets (sap.ui.core.dnd.DropPosition.On).
  • For dropping items on the same level, use the space between items as drop targets (sap.ui.core.dnd.DropPosition.Between).
  • If you want to allow users to drop items as a child or sibling, offer both drop targets (sap.ui.core.dnd.DropPosition.OnOrBetween).

This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Do not combine rearranging items within one level and sorting. If you really need to do so, make sure there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

Moving items from one node to another can be combined with sorting without any issues.

Drop targets in between items
Drop targets in between items

Visible Alternatives to Drag and Drop

Depending on the functionality you need, use one or more of the following alternatives:

  • To move items up or down within a node:
    Use the  Move Up and  Move Down buttons on the toolbar. These buttons move the selected items until the first selected item can’t be moved up or the last selected item can’t be moved down any further.
    Depending on your tree, this can make sense for both leaves and nodes, only for leaves, or only for nodes. When moving a node, move the whole node and (if applicable) all its children up or down to the next position within the parent node.
    Always make sure that when the user moves an item in one direction and then moves it back, the order is the same as it was before.
    Do not combine the option to move items up and down with sorting.
  • To move items to another node:
    Use Copy and Paste buttons on the toolbar.
    Alternatively, offer a Move To button. Clicking Move To opens a dialog that shows all the nodes of the tree, but no leaves. Selecting an item in this dialog closes the dialog and moves the corresponding items to the selected node.
  • To change the level of an item:
    In some trees, such as document structures, users can change the level of an item without affecting the level of parent or child items. In this case, use left and right arrow buttons (   ).

Filtering

What exactly needs to stay or be removed is highly dependent on the kind of structure and data your tree displays. For many trees, the following approach works well if you want to apply filters only to the leaves of a tree:

  • Remove all leaves that don’t fit the filter criteria
  • Remove empty nodes

If you also apply filters to nodes, keep the following in mind:

  • A node may or may not fit the filter criteria.
  • A node can contain items (nodes and/or leaves) that fit the filter criteria.

Because of this, the results might contain more nodes than those that are relevant for the filter criteria.

Developer Hint
The tree control itself has no influence on the filter result. It sends a filter request and displays whatever comes back. Make sure that the result set is meaningful.
[/vc_row_inner]

Sorting

Before you start, ask yourself if sorting is meaningful in your tree. If so, decide on a meaningful default sort order.

If sorting is meaningful, is it meaningful on all levels? Or does the tree structure need to be stable? In the latter case, sort only leaves, but not nodes.

The descending sort order must always be the exact reverse of the ascending sort order. Use a meaningful sort order. For example:

  • Sort text alphabetically
  • Sort numbers by their value
  • Sort status information by the severity of the status:
    • Ascending: Sort status information from positive to negative, with neutral last.
    • Descending: Sort status information from negative to positive, with neutral first.
    • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
    • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting the tree data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button
'Export to Spreadsheet' menu button

Resources

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

Elements and Controls

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 added manually or generated by the system (for example, value XY changed from A to B). The latest entry is always on top.

Another use case is a feed that is driven by user updates and comments. This feed can also be entirely devoid of machine-generated content.

Information
Do not confuse the timeline control with the similar-looking group feed component. While the group feed component was created explicitly for integration with SAP Jam, the timeline is more flexible, fully responsive, and not restricted to a specific source. However, the timeline control doesn’t offer any integration with social collaboration platforms out of the box.

Usage

The timeline does not have a fixed location on the UI. Where you place it 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. Alternatively, you can create a separate page with the timeline as the central element and show it next to the main content using the flexible column layout.
  • 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.

If you also require social collaboration features, you have two options: For integration with SAP Jam, you can use the group feed component, which offers similar features to the timeline. For integration with other social collaboration solutions, you can use the timeline control, but the integration does not come out of the box and needs to be provided by the app team.

Use the timeline if:

  • You want to display read-only content, such as an object history.
  • Your customers do not use SAP Jam.
  • You expect a long list of posts triggered by the system, the users, or both.
  • You want users to be able to create their own posts.
  • You want to offer custom actions for individual items.

Do not use the timeline if:

  • You expect only a few entries. In this case, use a simple feed.
  • You want to provide a way to upload files. Use the upload collection control instead. You can still use the timeline to show automated updates about the user’s uploads.
  • You need SAP Jam integration. In this case, use the group feed component.

Responsiveness

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

For better usability, both the single-sided and the double-sided layouts have a maximum width. This prevents the control from being excessively stretched.

For size S (smartphone), we highly recommend using the single-sided layout combined with narrow containers, such as the dynamic side panel. Also use the single-sided layout if the column in the flexible layout is too narrow for the double-sided layout. As soon as you have enough screen real estate, switch to the double-sided version to fully utilize the available space.

The single-sided version has a maximum width of 30 rem, while the double-sided layout has 57.5 rem.

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, but highly recommended)
  • A chronological axis
  • Posts/entries

The following optional features can be added:

  • 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 entered manually or generated by the system (for example, “Object ABC was changed by Mr. X”). The entry should include information about who changed what, and when (depending on the use case). 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 action section containing actions that can be performed on an item, such as Edit or Delete. Actions are provided by the application.

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

Timeline – Layout
Timeline – Layout

Here are just a few examples of different visualizations. Because the timeline control is very flexible, there are also numerous other possibilities.

Timeline – Layout examples
Timeline – Layout examples

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: Can someone please have a look at these numbers?

  • Post triggered by user action: The post is triggered by something a person does (such as creating an object, adding a note, or uploading an attachment).

Examples:

Julie Armstrong created sales order 4815162342.
(Followed by an optional preview of the header data)

John Miller uploaded the document Sales-Revenue_Q4.xls
(Followed by an optional preview of the document, if available)

Donna Moore added a note:
(Followed by an optional preview of the note)

Julie Armstrong added the picture our_team.jpg
(Followed by an optional 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 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 the same character 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

The timeline offers many levels of expansion, ranging from a simple read-only history to a highly interactive mode. This flexibility allows the timeline to cater for a wide range of use cases.

For example, you could use a read-only version to show system-generated posts that don’t require any user interaction. Nevertheless, this timeline could still be used to show actions the user has taken within the app (like creating notes and attachments, or making calls). These actions appear in the timeline as application-generated posts.

Example of a basic read-only use case.
Example of a basic read-only use case.
Example of a highly interactive history feed
Example of a highly interactive history feed

Behavior and Interaction

Search

Because a timeline can contain a vast number of entries, always offer a search. 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 the icon opens the search field with the focus in the field so the user can start typing.

Expand and Collapse

Some updates might be too lengthy to show in full. For these cases, applications can decide to show only a preview and let users expand the post if they want to read it. You can set a limit for the number of lines to be shown (recommended), or for the number of characters.

This example shows a post that previews 3 lines before truncating and showing a More button in the next line. Clicking this button expands the post to its full length and changes the button text to Less. Clicking this button again collapses the post to its previous height.

Interaction – Expand/collapse
Interaction – Expand/collapse

Filter (Optional)

For timelines with several entries or 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). Users can even filter by time range to find posts between two specific dates, months, quarters, or years.

The filter is triggered with the filter icon  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.
Timeline interaction – Filter with view settings dialog
Timeline interaction – Filter with view settings dialog

If a filter is set, inform the user in the infobar.

Timeline interaction – Set filter
Timeline interaction – Set filter
Developer Hint
As of SAPUI5 version 1.48, sorting and filtering is no longer restricted to the front end. The timeline offers full filter and sorting support for model binding.

Scrolling

The timeline offers endless scrolling. As soon as the user reaches the end of the pre-loaded list, more posts are fetched from the back end.

Developer Hint
To enable infinite scrolling, set the properties GetLazyLoading and EnableScroll to “true”.

In exceptional cases, it might be more useful to let users trigger the fetching process manually. Once the number of entries displayed in the timeline exceeds the number of entries set, a Show More button appears at the bottom of the list for loading additional posts.

Each app team can determine the number of entries displayed before the Show More button appears, based on the specific use case and app performance.

Use the Show More button instead of infinite scrolling if you expect users to look at only the most recent posts and do not expect them to scroll through longer lists of posts.

Grouping

The timeline allows applications to group posts by certain criteria (for example, by year). Groups can be expanded and collapsed for a better overview.

Grouping is supported by all timeline types and layouts: vertical and horizontal as well as left-, right- and double-sided.

The following example shows two collapsed groups (2018 and 2017) and an expanded group (2016).

Timeline interaction – Grouping
Timeline interaction – Grouping

Custom Actions

You can introduce custom actions for timeline posts. Keep in mind that the available space is limited and translated words can take up much more space than their English counterparts. Only offer actions that are essential to your users and reduce the number of actions to a minimum. If more actions or more complex interaction is required, let your users navigate to a separate page for the item they need to work on (such as an object page).

In the first example, 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 the second 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 interrupt users while they are reading), the timeline offers a very subtle way of notifying users about new posts.

You can place a message strip directly below the toolbar to show how many new posts are waiting to be retrieved from the back end.

Behavior – Refresh
Behavior – Refresh

If a filter is active, the message strip shows alongside the filter infobar.

Behavior – Refresh and filter
Behavior – Refresh and filter

Social Actions

The timeline does not offer integrated social collaboration features out of the box. For integration with SAP Jam, see the group feed component.

If you want to build your own social platform or integrate an existing service other than SAP Jam, the timeline is flexible enough to handle most social collaboration features. The following section gives some guidance on how to design the interaction.

Adding a Post

You can allow users to add their own posts by offering a plus  icon in the toolbar on top of the timeline.

Use the plus   icon to trigger a popover containing a text area. Set the focus inside the text area to enable the user to start typing right away.

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

Interaction – Adding a post
Interaction – Adding a post

Replying to a Post

Alongside the Post function, Reply is probably the most basic and essential social feature. Unlike feed controls (sap.m.FeedInput and sap.m.FeedListItem), the timeline enables communication at item level. Feed controls always add entries to the top of the list; there are no inline replies within the feed. By contrast, the timeline lets users reply directly to a specific entry. The number of replies is shown next to the Reply action, for example, Reply (5).

When the user clicks the Reply link, the app needs to trigger a popover that shows all previous replies, as well as a text area for posting a reply.

Interaction – Reply
Interaction – Reply

Styles

Orientation

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.
(See guidelines section for more details.)

Vertical

Use the vertical timeline for narrow containers or on smartphones (in portrait mode).

Styles – Vertical (single-sided), right
Styles – Vertical (single-sided), right
Styles – Vertical (single-sided), left
Styles – Vertical (single-sided), left
Styles – Vertical (double-sided)
Styles – Vertical (double-sided)

Horizontal

You can use the horizontal timeline on wide screens, the object pageor even on smartphones in landscape mode.

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

Styles – Horizontal (single-sided), bottom
Styles – Horizontal (single-sided), bottom
Styles – Horizontal (single-sided), top
Styles – Horizontal (single-sided), top
Styles – Horizontal (double-sided)
Styles – Horizontal (double-sided)

Icons vs. Bullets

When you design your application, you can chose between two visualizations for listing posts on the timeline: icons or bullet points.

You can use icons if all entry types that will appear in the timeline can be represented by an icon.

If you cannot find icons for all post types, use bullet points instead.

Styles – Vertical with icons
Styles – Vertical with icons
Styles – Vertical without icons
Styles – Vertical without icons

Colors

You can use colors to highlight entries in the timeline and to convey semantic information (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

  • 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. Only use colors to convey semantic information (for example, warnings or errors).
  • When using the vertical timeline, use single-sided (right) or double-sided layout, unless the use case calls for the left-sided version.
  • When using the horizontal layout, use the single-sided (bottom) or double-sided version, unless the use case is better supported by the top-sided version.
  • When you choose the layout, consider the type of content and the screen real estate available for displaying the control. For example:
    • In a vertically-oriented dynamic side content container, also use vertical orientation for the timeline. Likewise, if the container is oriented horizontally (either by design or due to responsive behavior), the timeline should also be horizontal.
    • If sections on an object page offer more horizontal than vertical space, use a horizontal timeline. This can be either single-sided (bottom) or double-sided.

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

Button

Buttons allow users to trigger an action. There are 4 button types:

  • Simple button for one action
  • Toggle button to switch between different states
  • Segmented button with a group of options
  • Menu button with a group of actions
Common button types
Common button types

Usage

Use the button types as follows:

  • Use simple buttons for specific actions, such as:
    • Create, Edit, Save
    • Approve, Reject
    • Accept, Decline
    • OK, Cancel
  • Use toggle buttons in a toolbar to activate or deactivate an object or element. You can also use toggle buttons to switch between different states.
  • If you want the user to select one option from a small group, offer a segmented button in the toolbar. For example:
    • Year, Month, Day
    • Small, Medium, Large
  • Use the menu button if you need a menu that provides more than one option.

Do not use buttons if:

  • You want to link to a different page or object. Use the link instead.
  • You want to let users upload content. Use the upload collection control instead.

Responsiveness

The button usually grows to fit the size of the text. If you set a fixed size for the button, the text truncates.

If the button is used in a responsive container or toolbar, it follows the responsive behavior defined for that element. For example, the button can move to another line.

Buttons with different lengths
Buttons with different lengths

Menu Button

The maximum width of the menu button is 12 rem (192 px). If the button text exceeds the maximum or fixed width, it truncates.

On smartphones (size S), the menu opens in a full screen dialog, and the button label becomes the title of the dialog. The footer contains a Cancel button. Items with submenus become navigable. Navigation is similar to that used in a popover, with a Back button.

On tablet and desktop devices (sizes M and L), the menu button triggers a cascading dropdown menu.

Open menu button
Open menu button
Menu button popover on size S
Menu button popover on size S

Types

Button

Buttons can trigger primary, secondary, semantic, and negative path actions. These different action types are explained in more detail in the action placement guideline.

Header and Footer Toolbars

Use the following button styling for the different action types in the header and footer toolbar:

  • Primary action: Use the emphasized button style.
  • Secondary action: Use the ghost button style. 
  • Semantic action: Use the semantic buttons for positive and negative actions. Use the “accept” style for positive actions, and “reject” for negative actions. Semantic actions must always be text buttons.
  • Negative path action: Use the transparent button style.

Content Toolbars

Use the following button styling for the different action types in content toolbars (for example, in tables, forms, or charts):

  • Primary action: Use the emphasized button style. Usually, the primary action is positioned in the header or footer toolbar. Note that there can only be one primary action per page. If a page already has a primary action, but you also need to highlight the most important action in a content toolbar, use the ghost styling for this one button in the content toolbar.
  • Secondary action: Use the transparent button style.

The different button styles are designed to give appropriate feedback to users. Don’t use them for decoration purposes.

Button with different styles
Button with different styles

Toggle Button

A toggle button switches between two actions. One of the actions is always active, one is inactive. Use the toggle button for secondary actions.

Apply the following button styles for the different toolbars:

  • Header and footer toolbars: Use the ghost button style.
  • Content toolbars: Use the transparent button style.
Toggle buttons
Toggle buttons

Segmented Button

A segmented button shows a group of options. Only one of the options can be active, the others remain or become inactive. Pressing an option activates it. By default, the control for segmented buttons calculates the button width and applies it to all buttons within the group. You can change this by setting the width for individual buttons.

The segmented button is comparable to a radio button group control.

Segmented buttons
Segmented buttons

Menu Button

There are two different types of menu buttons. Both can contain items with submenus.

Regular Menu Button

When the user activates the button, the menu opens. This is the default type.

Split Menu Button

The split menu button is separated into two areas: the text label and the icon. The separator between them signals that the two areas result in different actions. The user has two choices: activating the text label on the button triggers the action. Activating the arrow opens the menu. The split button consolidates a variety of commands, especially when one of the commands is used more often.

In split mode, the text label depends on the default action. If the default action is displayed as an icon only, all the menu items must contain icons.

Split Menu Button Behaviors

The split menu button can have two different behaviors:

  1. The button always triggers the default action set by the app developer. If no default action has been defined, the first item in the menu list becomes the default.
  2. The button triggers the last action chosen by the user. Initially, it also triggers the default action. However, when the user selects a different action, this user action becomes the default, and the button text label changes accordingly. The button has a fixed size and the text truncates if the menu item exceeds the available width (as with the combo box).

Toolbars

Apply the following menu button styles for the different toolbars:

  • Header and footer toolbars: Use the ghost style.
  • Content toolbars: Use the transparent button style.

Do not use any other styling types.

Menu buttons
Menu buttons

Components

A button can contain an icon OR a text.

Always use a text button for primary, secondary, semantic and negative path actions.

Use icon buttons only if the icon metaphor is easily recognizable. Ideally, it should have same meaning worldwide.  For more information about icons in general, check out the article on iconography.

Button Shortcut

The button shortcut control is a tooltip visualization of the keyboard shortcut for an action. It appears on hover or on keyboard focus, and its positioning (top or bottom) is context dependent. In cases where a tooltip is needed, it is combined with the shortcut information.

Button with a shortcut tooltip
Button with a shortcut tooltip

Behavior and Interaction

To trigger the action, the user clicks the button, toggle button, or segmented button using a keyboard, touchscreen or screen reader. The button provides visual feedback for “hover”, “press-down”, and “focused” states.

  • A toggle button remains in the pressed state until it is pressed again.
  • In a segmented button, the chosen option stays active until the user presses one of the other options.
  • menu button displays a dropdown menu on activation.
  • In a split button, selecting the button text triggers that action directly. Activating the arrow opens a dropdown menu. If the user selects a menu item, the action is triggered and the menu closes.

If an action cannot be triggered, or is temporarily unavailable, use the disabled state for the corresponding button.

All three button types support the cozy and compact form factors. For more information, check out the article on content density.

Regular state
Regular state
Hover state
Hover state
Press-down state
Press-down state
Disabled state
Disabled state
Focused state
Focused state
Opening a menu button with subitems
Opening a menu button with subitems

Guidelines

Button Text

  • Choose a button text that is short and meaningful. Check out the UI text guidelines for more information.
  • Use a verb in the imperative for all actions (for example: SaveCancel, Edit).
    Note: The grammatical form for actions can differ for other languages. For example, German action labels use the infinitive (Speichern, Abbrechen, Bearbeiten).
  • Keep in mind that the text can be up to 300% longer in other languages.
  • If you need to show the number of items that will be affected by the action of the button, you can add the number in parentheses. For example, Edit (3).

Icon Buttons

  • Make sure the default accessibility text for the icon is correct for your use case. If the text is not ideal, define an app-specific accessibility text.
  • Offer a tooltip to show the label for icon buttons.
  • Don’t use the icon control for buttons. Use the icon property for the button instead.

Examples

Header toolbar with primary action (emphasized styling) and secondary actions (ghost styling)
Header toolbar with primary action (emphasized styling) and secondary actions (ghost styling)
Table toolbar with search field, text buttons (ghost and transparent styling), icon buttons (transparent styling), and segmented button
Table toolbar with search field, text buttons (ghost and transparent styling), icon buttons (transparent styling), and segmented button
Footer toolbar with standard actions: 'Save' (emphasized) and 'Cancel' (transparent)
Footer toolbar with standard actions: 'Save' (emphasized) and 'Cancel' (transparent)

Related Links

Elements and Controls

Implementation


  • No links

Range Slider

A range slider is a user interface control that enables the user to select a value range within a predefined numerical interval.

Range slider
Range slider

Usage

Use the range slider if you want to select a value range within a predefined numerical interval. If you want to specify only a single value within a predefined numerical interval, use the slider instead.

Responsiveness

The range slider itself is not responsive. It adjusts to the responsiveness of its parent container by recalculating and resizing the width of the control. The range slider supports the cozy and compact form factors.

Types

Only a horizontal range slider is available.

Components

The range slider consists of:

  • Progress line
  • Minimum and maximum value
  • Grips
  • Tooltips or input fields
Range slider components
Range slider components

Behavior and Interaction

Changing Values

If the range slider is editable, the hand cursor appears when hovering over the range slider with the mouse. A tooltip also appears when hovering, displaying the current values of each grip. The grips move together with the corresponding tooltips.

The user can change the value range on the slider in two ways:

  • By using drag and drop to adjust the grips
  • By clicking the bar outside the value range. The corresponding grip then moves to the new position.

The grips can be moved with or without increments based on the predefined steps.

Range slider on hover
Range slider on hover

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

Users can move the entire value range by dragging and dropping the progress line.

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 with equal values
Range slider with equal values

Overlapping

The grips of the range slider can be moved across each other. The minimum can become the maximum, and vice versa.

Tick Marks

You can apply tick marks to the range slider. The tick marks are related to the step property. For example, if you have a range from 1 to 100 and a step of 10, the range slider will have 11 tick marks. The tick marks are responsive. If the distance between 2 tick marks is less than 8 px, all tick marks except for the first and last disappear.

Range slider with tick marks
Range slider with tick marks

Tick Marks and Labels

If tick marks are set, you can define labels for the tick marks. The labels are displayed below the tick marks and show the corresponding value of the tick mark. The labels must never overlap. You can also define labels only for specific tick marks if you don’t need a label for every tick mark on the slider. The application developer is responsible for defining a reasonable set of tick marks.

If there is not enough horizontal space to display all the labels, a responsive mechanism is activated. The first and the last label are always visible.

Range slider with tick marks and labels
Range slider with tick marks and labels

Custom Values

You can define custom values as labels. This can be useful if your scenario requires descriptive intervals, such as as dates. Always keep the values as short and meaningful as possible.

Range slider with custom values as labels
Range slider with custom values as labels
Developer Hint
In order to use custom scales in a slider, you must map them to the floats for the slider scale.

Properties

  • The step property must be positive. If a negative number is provided, the default value 1 is used instead.
  • The minimum, maximum, and value properties can be decimals (float values). The slider automatically sets the minimum value to 0 and the maximum value to 100 by default.
  • The width of the control can be provided in percentage (%), em, px, and all possible CSS units. The slider automatically sets the width of the slider to 100% by default.
  • The range property determines the range in which the user can select values. If the value is lower/higher than the allowed minimum/maximum, a warning message is displayed.
  • The inputsAsTooltips property indicates whether input fields are being used as tooltips for the grips.

Resources

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

Elements and Controls

Implementation

Micro Process Flow

Intro

The micro process flow control enables you to visualize the state of individual items in a linear workflow. You can embed it into a list or a table.

Micro process flows
Micro process flows

Usage

Use the micro process flow if:

  • You need to show the state of each step in a linear, multi-step process.
  • Users need to see the progress of multiple items displayed in a list or table at a glance.

Do not use the micro process flow if:

Responsiveness

The micro process flow is responsive and adapts to the size of its parent container. If the micro process flow is too long for the parent container’s width, you can choose how it should behave:

  • Simple wrap: Steps that don’t fit into the width of the parent container wrap to a new line.
Simple wrap behavior of micro process flow
Simple wrap behavior of micro process flow
  • Overflow: Navigation arrows appear on both sides of the micro process flow, with the number of hidden steps indicated next to each arrow. By clicking the navigation arrows, users can scroll horizontally through all of the steps in the micro process flow.
Overflow behavior of micro process flow
Overflow behavior of micro process flow

The micro process flow control supports cozy and compact form factors.

Layout

The micro process flow acts as a generic container in which process steps are laid out linearly along the horizontal axis. The control provides the following layout options:

Default

The process steps appear as icons with a circular background. They use semantic colors and provide click events. You can choose from different icons provided by the SAP icon font.

Guidelines
Always replace the default icons with icons that fit to your use case.
Default layout with a circular background
Default layout with a circular background

Custom

The default steps can be replaced by other controls. The following controls are supported:

Guidelines
Make sure that you replace the default tooltip texts from the original icons or controls with the names of individual steps in the process. For example, Payment, Shipping, Delivery. For more information, see Using Tooltips.
Custom layout using the 'status indicator' control
Custom layout using the 'status indicator' control
Custom layout using the 'micro chart' control
Custom layout using the 'micro chart' control

Types

There are two micro process flow types: one with dependent steps and one with independent steps.

Dependent Steps (Default)

The dependent steps come with a connector line that appears between the process step and the step that follows it. Use this type when the completion of a step is a precondition for the subsequent step.

Guidelines
When customizing the width of the connector lines, the minimum width must not be less than the default width, and the maximum width must not exceed the step width or step height (whichever is greater).
Micro process flow with dependent steps
Micro process flow with dependent steps

You can also indicate the state of the transition between two steps with a suitable icon.

Guidelines
The width of the icon must not exceed 60% of the connector line width. The height of the icon must not exceed the size of the step node.
Micro process flow with transition state
Micro process flow with transition state

Independent Steps

Independent steps are not connected and can be processed in any order. Use this type when the user doesn’t need to perform the steps in a linear sequence.

Micro process flow with independent steps
Micro process flow with independent steps

Guidelines

Popover with Step Details

Users often need more information about a step. To provide more details, add an on-click popover for each step. Also add a click event for each step to invoke the popover.

Micro process flow with on-click popover
Micro process flow with on-click popover

Exchange Default Icons

Always exchange the default icons and replace them with icons that best fit your use case and line of business.

Do
Use case-specific icons
Use case-specific icons
Don't
Former default icons
Former default icons

Resources

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

Elements and Controls

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

When suggestions are turned on, the suggestion list displays differently depending on the device type.

Size S (Smart Phones)

Clicking the search field opens a new full screen dialog in which items can be selected from a list of suggestions.

Size S
Size S

Size M (Tablets)

Suggestions are shown below the search field.

Size M
Size M

Size L (Desktops)

Suggestions are shown below the search field.

Size L
Size L

Types

SAP Fiori comes with two different search types.

  1. The manual search is triggered explicitly after the user enters text in the search field and clicks 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. There is a default delay of 400 ms before sending the search data to the back end. This ensures better performance and optimizes user experience. 

Queries that are entered are used to search the back-end 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 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 the “X” icon  ) 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.

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

Properties

The following methods are important.

For the live search:

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

For the manual search:

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

If a Refresh button is needed:

To show the Search button:

To ensure the focus is set to input:

If the search is triggered automatically when the value of the field is changed (unlike the liveChange event, the change event is not fired for each key press):

  • attachChange(oData?fnFunctionoListener?) Attach event handler fnFunction to the change event of this sap.m.SearchField.
  • detachChange(fnFunctionoListener) Detach event handler fnFunction from the change event of this sap.m.SearchField.
  • fireChange(mArguments?) Fire change event to attached listeners.

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

Contextual Filter

The contextual filter allows you to show a prefiltered view of a list, such as a master list.

Warning
Note that this filter prevents the regular filter (which is triggered from the filter bar or table toolbar) from displaying the filter criteria that are currently selected.

Usage

Use the contextual filter if:

  • You want to show the user a meaningful extract of an otherwise highly complex list.
  • Your app handles very large object lists, and you need to improve performance.

Do not use the contextual filter if:

  • You just want to provide a way to filter a list. In this case, use the regular filter instead.

Responsiveness

The contextual filter (sap.m.toolbar) spans the whole width of the list or table it is attached to, while its height remains unchanged. Text inside the bar does not wrap if there is insufficient space, but becomes truncated.

Contextual filter – Responsiveness
Contextual filter – Responsiveness
  1. Contextual filter with truncated text in a narrow container, such as on a smartphone.
  2. Responsive behavior on wider screens, such as on a tablet or desktop.

Layout

The contextual filter is shown as a bar directly above the master list. It comprises two parts:

  1. The filter value on the left (for example, a customer name).
  2. The icon for the filter criterion on the right (here, the object type “customer”). The icon helps the user to put the filter value into context.
Contextual filter – Layout
Contextual filter – Layout

Behavior and Interaction

The following example shows a prefiltered master list and explains how to change the filter criterion.

Change Filter

The user opens the app and sees a prefiltered list of objects. The bar on top of the master list indicates that the list is filtered, and which filters have been applied.

When the user clicks the bar, a screen (on phones) or popup (on desktops/tablets) appears for selecting additional filter criteria.

Contextual filter – Change filter setting
Contextual filter – Change filter setting

Select Filter Criterion

In this use case, the user should not be able to disable the filter because there is no way to reset it.

Other master list functions (such as Search or Refresh) are still available and remain unaffected by the contextual filter.

Once a criterion has been selected, the user is taken back to the master list (on phones) or the popup closes (on desktops/tablets). The list is now filtered by the newly selected criterion.

Contextual filter – Select filter attribute
Contextual filter – Select filter attribute

Guidelines

Do not use the contextual filter in place of the regular filter in the footer bar. The regular filter is much more versatile and can also be deactivated by the user.

Also note that both the contextual filter and the regular filter use the same infobar to visualize the filter criteria. If the contextual filter is being used, the regular filter can no longer be visualized. Although both filters can technically be used in parallel, we strongly advise against having both in one list.

Use an icon that is unique and visually represents the current filter criterion.

Do

Do not use any of the generic filter icons. They may be confused with the user-triggered filters.

Don't

Properties

The contextual filter is not a separate control. To build a contextual filter, you need to use the sap.m.OverflowToolbar control. The filtering itself must be implemented by the app team.

Exceptions

There is one special case where the contextual filter can actually be cancelled by the user. This applies when the contextual filter is used to prefilter the items listed in a select dialog.

This use of the contextual filter conveniently offers users a narrowed-down list based on their previous selection.

(1) Initial situation: The user is about to select an account and a contact.

(2) The user selects “Best Electronics” and then clicks the value help icon in the Contact field.

(3) The value help dialog appears showing a list of contacts. These are prefiltered (using the contextual filter) to show only contacts from “Best Electronics” (the company the user selected previously).

 

Note that this time the icon in the filter’s toolbar does not show an account icon, but a Remove icon   instead. This allows the user to cancel the filter if he or she wants to add a contact that is not associated with the account selected previously.

When the user clicks the Remove icon  , the filter is removed and the entire contact list is shown.

Once the user has selected a contact, the dialog closes and the name is added to the relevant field on the main page.

Opening the value help again resets the dialog to its initial state with the filter set to “Best Electronics”.

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

Feed and Notes

Feeds and notes are commonplace in many SAP Fiori applications. The sap.m.FeedInput control allows users to input and post plain text, while the sap.m.FeedListItem control handles and displays this text. Both can be used individually, but they also complement each other well to create a simple feed or notes control.

Usage

Feed Input

Use the feed input if:

  • A user needs to input small amounts of text without formatting.
  • You expect multiple instances, such as notes or feed entries.

Do not use the feed input if:

  • The user needs to format the text (rich text editor).
  • You need only a single text box instance. In this case, use the text area (for multiple lines) or the text control (for a single line).

Combination of Both Controls (as Feed or Notes Control)

Use both controls if:

  • You need a feed to show textual posts.
  • Your users need to input notes.

Do not use both controls if:

  • You expect extensive social interaction in the feed.
  • Users need to reply at item level instead of creating a new post.
  • You want to display SAP Jam feeds.

In these cases, use the social timeline instead (requires SAP Jam).

Responsiveness

Due to their responsive behavior, both controls can be used in small and large view ports or screens.

For better usability, we highly recommend that you do not stretch the controls across the full width on large screens – 2/3 or even 1/2 works just fine. This can easily be achieved using the grid layout .

Feed – Size S
Feed – Size S
Feed – Size M
Feed – Size M
Feed – Size L
Feed – Size L

When the width of the available space falls below 25 rem (for example, in portrait mode on smartphones), the two controls respond as follows:

  • If a user image previously appeared in the feed input, it will be omitted in narrow screens to give the text field more space.
  • If there is no user image, there will be no visual change.
Feed input – Responsiveness
Feed input – Responsiveness

In the feed list item, the user’s name, image, and the time stamp move on top of the text. If there is no image, the name and time stamp are left-aligned together with the text.

Feed list item – Responsiveness – With image
Feed list item – Responsiveness – With image
Feed list item – Responsiveness – Without image
Feed list item – Responsiveness – Without image

Layout

Feed Input

The feed input consists of:

  • A text input field with a placeholder (input prompt)
    Example: Add a comment
  • A Send button
  • An optional user image

You can also choose not to show user images at all. In this case, the size of the input area increases automatically.

Feed input – Layout – With user image
Feed input – Layout – With user image
Feed input – Layout – With generic user image
Feed input – Layout – With generic user image
Feed input – Layout – Without user image
Feed input – Layout – Without user image

Feed List Item

The feed list item consists of the user’s name and an optional picture of the user who wrote the note or update. The name can contain a link that triggers a quick overview of the user’s profile data. The actual text written by the user follows the name. Below it is a separate byline that can contain a time stamp and an attribute in the form of free text. This allows you to put in your own attribute, such as Approval, Internal, or External. Both the time stamp and the attribute are optional.

If the name is a link, the picture should also be linked with the same attributes.

Feed list item – With user image and linked name
Feed list item – With user image and linked name

If the user does not have a picture assigned, a placeholder is shown instead:

Feed list item – With generic user image and linked name
Feed list item – With generic user image and linked name

The name (and picture) can also be read-only, that is, without a link:

Feed list item – With user image but without links
Feed list item – With user image but without links

If the app does not support user images, they can be omitted:

Feed list item – Without user image but with linked name
Feed list item – Without user image but with linked name

Here, too, the name can be read-only:

Feed list item – Without user image and read-only name
Feed list item – Without user image and read-only name

It’s also possible to display rich text (formatted text) in the feed list item. This feature should be handled with care as it allows for countless custom layouts.

Please see that you use it responsibly and provide your users with a consistent experience. Only deviate from the default layout and font if absolutely required by the use case.

Example use case: Render URLs as links.

Feed list item – Layout – Rich text
Feed list item – Layout – Rich text
Information
The items in the feed list must be homogeneous. This means that they must contain the same layout and visualization. For example, it is not possible to have a feed containing both linked and plain names, or both user images and default images.

Special Case: Multiple Types of Notes

Apps sometimes need to discern between different types of notes. There is an easy way to allow users to choose which type they want to see or add to the list.

You can place a toolbar containing a select control at the top of the feed input control. From there, users can select the type of notes, such as Internal Notes or External Notes. The list of notes must contain only the type selected. If the user adds a note via the feed input, the type must be set automatically according to the selection.

Interaction – Note types (1)
Interaction – Note types (1)
Interaction – Note types (2)
Interaction – Note types (2)
Interaction – Note types (3)
Interaction – Note types (3)

Components

The feed input and feed list item do not contain subcontrols. However, you can easily combine them to create a simple feed or notes control.

Although the feed input counts as a single control, the input area inherits its behavior from the sap.m.TextArea control.

Behavior and Interaction

Send Message

Initially, the feeder contains a placeholder (input prompt), and the Send button is disabled, with reduced opacity.

Clicking into the input field puts the focus on the field and allows to start typing.

When the user starts to type, the placeholder disappears and the Send button becomes active and more prominent.

If the available width is below 25 rem (for example, in portrait mode on a smartphone), the picture is removed.

To send the text, the user must explicitly click the Send button. Pressing Enter on the keyboard (on-screen or physical) results in a line break.

Feed input – Behavior
Feed input – Behavior

Show More Text

When the text exceeds a certain number of characters (you can overwrite the default value), the rest of the text is truncated and a MORE link appears after the truncated section.

Initially, the MORE link is gray, so it does not divert the user’s attention away from the actual text. When the user moves the mouse over the feed text, the MORE link is highlighted. Hovering over the link underlines it.

Show Less Text

When the user expands the text, the name of this link changes to LESS,  but still behaves the same way as before.

Feed and Notes in Tables

In tables, users sometimes need to see if an object has a comment (or feed or note) without further navigation, and even be able to add/edit right from the table.

Add an additional row, named according to the type of user input, such as Comment, Note, or Feed.

Place a link inside each cell with the appropriate action (row: Comment, link: Comment/ row: Feed, link: Post).
If there can be more than one item, add a counter after the text as well (see example on the right).

This solution works with every table control.

Feed and notes in tables (1)
Feed and notes in tables (1)

Optional:
Depending on the use case, it might help users if they can see the latest note. The responsive table allows the feed list item (sap.m.FeedListItem) to be used inside a cell.

Reduce the property “maxCharacters” to an amount that your table can handle.
Note that once the maximum number of characters has been reached, a MORE link allows users to expand the text. Technically, this is no problem for the responsive table, but you need to ensure that the layout of your page allows this kind of expansion.

Place a link below the feed list item to allow users to add something (as described above).

Feed and notes in tables (2)
Feed and notes in tables (2)

When the user clicks a link, such as Comment or Note, display a dialog showing all comments (notes, feed entries, and so on) along with possible actions, such as Add or Edit, depending on your use case.

There are several ways to show notes (comments, feed entries, and so on) in a dialog:

  • You can use the feed list item (and feed input) as described in this article.
  • If only one single note is allowed, you can use the text area.
  • For a large feed, you can use the timeline control (SAP Jam is required for social features).

Actions On Feed List Items

Applications can define actions that users can perform on individual feed posts. The two most typical actions are Edit and Delete. Other actions can be introduced as required by the use case. To keep the feed as lightweight as possible, don’t overwhelm users with too many actions or complicated actions (max. 5 per post).

Interaction - Actions
Interaction - Actions

Styles

By default, feed entries are separated by divider lines. We recommend that these separators remain enabled, since they help distinguish between individual posts. However, if your list is expected to hold only a handful of entries, you can disable the separators by setting the showSeparators property at list level (not at list item level) to none.

Guidelines

Because the feed list item is built on the basis of the standard list item, it inherits multiple properties that may not make sense in a feed use case.

Use only properties that are described in this article. Especially making the entire feed list item clickable can lead to functional issues and usability problems.

Don’t stretch the feed input or the feed list items across large screens (size L and beyond). This will have a negative effect on usability and readability. Instead, only use 1/3 or even 1/2 of the screen. Implement this with the grid layout .

If you display formatted text (rich text) in the feed list item, use formatting that is beneficial to users, not decorative formatting. Use formatting responsibly, and provide your users with a consistent experience. Deviate from the default layout and font only if absolutely required by the use case (example: render URLs as links).

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

Grid List

As with the list and the responsive table, the grid list displays a set of items. In contrast to both controls, the grid list displays the items not in rows, but in a grid.

The grid list is usually used as an alternative view for a list or table. It is ideal for displaying images, charts, object cards, and other content, which profit from more height (but less width).

Grid List
Grid List

Usage

Use the grid list if:

  • Your content is “visual” and profits from the rectangular format of the items. This is true for e.g. images, charts, and object cards.
  • The focus is on items, not on cells. The grid list shows complete items.
  • You want to display a homogeneous set of basic data.
  • You need to sort, group, or filter simple data sets.
  • As an alternative view for tables or lists, if the content profits from the different format.

Do not use the grid list if:

  • Your content is not appropriate for a card-like format. For example, do not use the grid list for displaying a wall of text. Use a table instead.
  • 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.
  • Data needs to be structured in a hierarchical manner. In this case, a tree might be more appropriate.
  • 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 the CSSGrid.
  • You want to manage complex datasets that need to be extensively sorted, grouped, filtered, or edited. In this case, use a table.

Responsiveness

The responsiveness of the grid list results from the underlying grid. The underlying grid is defined by rows and columns. Columns can have a minimum and maximum or a fixed size. Whenever an additional column fits on the screen, it will be added. If a column does not fit on the screen anymore, it will be removed. Items are re-layouted accordingly.

Optionally, there can be different configurations for the underlying grid based on breakpoints, for example based on the device types.

To define the grid layout and behavior, you can use one of the pre-defined layouts:

  • Grid box layout: Adds a variable number of columns depending on the available screen width. Columns have either a fixed width or can “breathe” slightly. All rows have the same height, and all items are the same size.
  • Responsive column layout: The number of columns depends on breakpoints (4 columns for size S, 8 for size M, 12 for size L, and 16 for size XL). The width of the columns grows or shrinks with the available screen space until the next breakpoint is reached. The row height of the grid is determined by the height of the highest item in the row. The number of rows and columns taken up by an item can differ.

Alternatively, you can define your own grid. This gives you much greater flexibility to influence both the layout and the (responsive) behavior of the grid.

The underlying grid defines the available space per item. The width can differ pending on the screen width (“breathing”) or be fixed. The height can differ pending on the content of the item or be fixed. “Breathing” items make better use of the available screen space and is therefore recommended. Make sure, that the item adapts to the resulting width / height, for example by

  • Re-layouting the item content
  • Hiding less important information
  • Re-sizing content, such as images or charts.

Items can use one ore more grid cells. Items can also be different sizes (for example, to allow for varying text lengths/wrapping in different items).

Size S
Size S
Size M
Size M
Size L
Size L

Components

  • The title bar holds the title and, an item counter. Instead of a title bar you can use a toolbar, including title, counter, variant management and actions.
  • Optionally, a filter infobar should appear when the grid list is filtered and shows information on the filter settings.
  • The collection of grid list items, layouted on a grid, occupies the main part of the grid list.
  • 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. Use More only, if content is shown below the grid list.
  • The footer can contain additional static text information.
Schematic visualization of the grid list
Schematic visualization of the grid list

Title Bar

The title bar contains the title of the grid list and an item counter

Title Bar
Title Bar

Instead of the title bar, a toolbar can be used instead. If done so, use a title control to display the title and item count. Variant management and actions can be added in this case. The toolbar can contain entry points for the view settings dialog, as well as view switches in the form of a segmented button, and buttons for actions like for example Add, or Edit.

Toolbar instead of title bar
Toolbar instead of title bar

For the title, keep the following in mind:

  • Use a title if you need the item count, toolbar actions, or variant management. To avoid repeating text, feel free to use generic text as a title, such as Items.
  • Do not show the title bar at all, if all elements (title, item count, variant management, toolbar) are available in the surrounding area.
    Example: An object page (sub-)section contains only one grid list. In this case, add the item count and the toolbar to the (sub-)section header.
Developer Hint
Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table. If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

For displaying the item count, use the following format:

[title text] ([count])

for example:

Items (2,534)

For the item count, keep the following in mind:

  • include all the items that a user can reach by scrolling except group headers.
  • Remove the item count if there are zero items.
  • Do not show a count on the title bar, if a More button is used. Show the count on the more button instead.

If possible, keep the title bar sticky (sap.m.GridList, property: sticky).

Filter Infobar

Beneath the toolbar, display a filter infobar (which itself is a special toolbar) if the grid list is filtered.

Filter infobar
Filter infobar

Items

The items (sap.f.GridListItem) are placed on a grid. To specify the design of items, it is recommend (but not mandatory) to follow the guidelines for object cards. Be aware that the item itself is responsible for its own responsiveness.

Use the grid list only, if your content profits from the format. This can apply to images, charts, but also to object cards or quick views. Another option is to mimick the format (but not the visual) of existing objects (e.g. business cards).

A grid list item can contain any content. This includes single controls, or a combination of controls (e.g. by using layout containers).

When designing an item,

  • Use the grid list item as starting point and make sure that the content adapts responsively to a changing item width / height.
  • Although the grid list can technically work with other list items (e.g. the standard list item), do not use them. They are not responsive enough for being used in a grid. In addition, selectors, navigation indicators and other elements are layouted differently (optimized for the list, not for the grid list).
  • Take care that an item can be identified, e.g. by adding a title, and if needed a sub title.
  • To show a string with an ID as identifier, use the title for the string, and the subtitle for the ID.
  • For status information, use semantic colors on foreground elements.
  • Avoid truncation. Use controls that wrap the text and configure them accordingly.
  • If an edit mode is needed, change your text controls (labels, text, and links) to input fields or other appropriate editable 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 item.

Not all items have to follow the same structure. This could be the case if one item is locked, but another item is in edit mode. Another example is to show a set of objects of different types in the same grid list.

Example for a grid list item
Example for a grid list item
Another example for a grid list item
Another example for a grid list item

Highlight

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

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry- / process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users what exactly is wrong. Make sure that you provide this information within the item, ideally in the same color.

For details on the usage of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted item
Highlighted item

States

To show that an item is unread, use the corresponding flag (sap.m.GridList, property: showUnread, sap.f.GridListItem, property: unread). This shows most of the content in bold font.

Unread item next to a read item
Unread item next to a read item

To show that an item has been modified, for example, within the global edit flow, add the string (Modified) near the item identifier.

A modified item
A modified item

To show that a modified item contains an error (for example, within the global edit flow), add the string (Contains errors) near the item identifier. To do this, use an object status control with the error state (sap.m.ObjectStatus, property: state, value: sap.ui.core.ValueState.Error). In addition, highlight the item accordingly (sap.f.GridListItem, property: highlight).

An item with an error
An item with an error

To show that an item is locked, use a transparent button with the corresponding icon and the text Locked by [Name] near the item identifier. The user can click 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 near the item identifier. The user can click the button to open a popover showing the timestamp of the last change.

An item with draft state
An item with draft state

Show only one state at any one time.

“More” Button

The More button loads more items to the front end if not all items have yet been loaded.

"More" button

Footer

The footer can be used to display additional static information relating to the content.

Grid list footer
Grid list footer

Behavior and Interaction

Scroll

The height of the grid list is defined by the number of items it contains. It does not have a scroll container on its own but is scrolled together with the page. When the user scrolls the page, the title bar and filter infobar can stick to the top of the surrounding layout container (sap.m.GridList, property: sticky).

Information
The “sticky” feature comes with some limitations:

  • It is not available on all browsers. In non-supporting browsers, the corresponding areas (title bar, filter infobar) are not fixed on top of the surrounding layout container while scrolling.
  • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the grid list is placed within the object page.
  • If focus is set to a fixed column header, the grid list is automatically scrolled to top.

Sticky toolbar
Sticky toolbar

Showing more items

If the grid list works in a “growing” mode, it only loads a few items at first. Additional items are only loaded (and rendered) on request. This request can either be triggered by scrolling (preferred), or by clicking the More button. Use the latter one only if content follows below the grid list. Use the “growing mode”, if more than 200 items are expected to be displayed.

If using the “More” button,

  • show the number of items already loaded and (if possible) the total number items below the text More.
  • do not show an item count on the title bar. Use the count on the More button instead.

In any case, if the “growing mode” is used, do not show more than 1,000 items overall.

Select

A grid list can have one of the following selection modes (sap.m.GridList/ sap.m.ListBase, property: mode):

  • None: Items cannot be selected (sap.m.ListMode.None).
    Beware: Items can still use the sap.m.ListType “navigation”, which allows click handling on specific items. Only use this option if the click triggers navigation to a corresponding item details page.
  • Single selection master: One item in the grid list can be selected. Items are selected by clicking the whole row. The single select master mode has no obvious visual cues, such as checkboxes or radio buttons. It only provides a light blue background for the selected state. Because of this, it can barely be differentiated from grid lists without selection (mode: None). Single select master is the preferred mode for single selection. (sap.m.ListMode.SingleSelectMaster).
Selected item in
Selected item in "single selection master"
  • Single selection left: One item in the grid list can be selected. For this, the grid list provides radio buttons on the left side of each item. Only use this mode if a click on the whole item is being used for something else, such as navigation. (sap.m.ListMode.SingleSelectLeft). Even in this case, prefer single select master and synchronize the selection with the navigation, so that the navigated item is also the selected item.
  • Multi selection: Users can select one or more items. For this, the grid list provides checkboxes on the left side of each item. (sap.m.ListMode.MultiSelect). The Shift key can be used to select a range. Try to avoid combining multi selection with navigation.
An unselected and a selected item in
An unselected and a selected item in "multi selection"

For all single selection modes, make sure that one item is initially selected. Otherwise, the user cannot return to the initial state. A selected item can only be deselected by selecting another item.

Click an Item

The whole item can be clickable. An event is fired by clicking the item (anywhere where there is no interactive control inside the item). Apps can react on the event, for example, by opening a dialog (sap.f.GridListItem, 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 grid list in “single select master” mode.

Drag and Drop

One or several items can be repositioned within a grid list or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

When using drag and drop, keep the following in mind:

  • Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, it is not accessible, since there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.
  • If you offer drag and drop for rearranging items within the grid list, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).
  • Be aware that due to the re-arrangement of the items which happens after an item is dropped, it is not always clear where the item will finally be placed.
  • When dropping items from outside the grid list, adapt the size of the drop indicator to match the target layout of the item (sap.f.dnd.GridDropInfo, property: dropIndicatorSize).
  • Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.
  • When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on a specific data point, the dropped item needs to take on the value of the target group for the corresponding data point. If this is not wanted, do not allow users to rearrange items in grouped grid lists. Example:
    A grid list is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Loading Data

To indicate that the grid list is currently loading items, use the busy state. (sap.m.GridList, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Empty Grid Lists

Try not to display an empty grid list. If there is no way around this, provide instructions on how to fill the grid list with data (sap.m.ListBase, properties: showNoData, noDataText).

Examples:

  • If a grid list is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the grid list with data.
  • If a grid list is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    To start, set the relevant filters.
  • If a grid list is used together with a filter bar and the filter does not return results, use the following text:
    No data found. Try adjusting the filter settings.

Adapt the texts above if:

  • The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of filter settings).

Context Menu

You can attach a context menu to a grid list. The context menu gives users an alternative way to modify the whole grid list or an individual item by providing access to context-specific actions. A context menu is opened by right-clicking (mouse), long press (touch devices), or via keyboard using the context menu key or SHIFT+F10. If a control inside a grid list is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar). Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

Be aware that using the context menu overrides the browsers context menu, which can no longer be opened.

Group

If grouped, a group header is displayed (sap.m.GroupHeaderListItem) above all items which belong to the corresponding group. The group header is not interactive.

A grouped grid list
A grouped grid list

Guidelines

Actions

To trigger actions on multiple items, use a multi-selection grid list (sap.m.GridList, property: mode, value: sap.m.ListMode.MultiSelect), and offer the corresponding actions on the toolbar of the grid list. Keep the toolbar sticky (sap.m.GridList, property: sticky).

In rare cases, you can also offer the corresponding actions in the footer toolbar. Do this only if the grid list is the only area on the screen to which actions can be applied and if the actions are finalizing.

Do not offer actions for multiple items if the grid list is expected to have fewer than 10 items in most cases.

To trigger actions on a single item only (sap.m.GridList, property: mode, value: sap.m.ListMode.SingleSelectMaster), the action can also be shown within the item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every item 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. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

The following actions on single items must always be in-line:

  • Delete: Use the “Delete” mode of the grid list (sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This places a Delete button at the right side of an item. Clicking 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 grid list and therefore cannot be used together with single selection or multi-selection.
Delete button
Delete button
  • Navigation: Use the “Navigation” item type (sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This places a Navigation indicator at the right side of an item and the entire item becomes clickable. Use this to navigate to a new page containing item details. In rare cases, you can also use this for the category navigation pattern without navigating to another page. By contrast, clicking an interactive control within an item does not trigger the navigation event. Instead, the corresponding control handles the click event.
    “Navigation” is an 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: Use the “Detail” list item type (sap.f.GridListItem, property: type, value: sap.m.ListType.Detail). This places an Edit icon at the right side of an item. Clicking the button triggers the edit event. Use this event to switch the corresponding 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

From these three actions (delete, navigation, and edit), you can combine delete and edit, or delete and navigation. Edit and navigation cannot be combined.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the responsive table. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning
The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

  • The number of rows in the table
  • The number of displayed columns
  • The complexity of the cell content (for example, simple text vs. complex charts)
  • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
  • The browser being used

Add Items

  • Place the Add or Create text button on the toolbar of the grid list.
    • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
    • Use Add if the item already exists and is merely added or assigned to the current object.
  • Place new items always as the first item of the grid list.
  • Use highlight (information state) on the new item.

After pressing the Add button, there are three possibilities for adding an item, which should be considered in the following priority:

  • Add the item inline. Create an empty, editable item as the first item of the grid list. Show the Save button on the toolbar of the grid list. This option is recommended for simple scenarios where just a few input fields have to be filled.
  • Open a dialog for items where up to 8 input fields need to be filled. Save the new item at the dialog level.
  • Navigate to a new page. This behavior should only be used for very complex scenarios that cannot be handled by a dialog (for example, creating complex objects). When the user presses Save in the footer toolbar of the create page, navigate back to the grid list.

There are three different states of a new item:

  • New: The item was just created and is still in edit mode. It is highlighted with a visual indicator (information state).
  • Recent: The item was saved but is still highlighted and displayed as the first item of the grid list. Current filter, sort and group criteria are ignored since the item should remain visible.
  • As soon as the grid list is sorted, filtered, or grouped again, the new item is handled accordingly and loses the visual highlight, but not before.

In the context of the draft handling new items are not saved on grid list level, but rather with the entire draft.

Export to Spreadsheet

Mass Editing

  • Provide multiselection (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.

For details, see mass editing.

Paste

To paste data from the clipboard to the grid list, the browser functionality for paste can be used (CTRL + V or browser context menu).

If the focus is on item level, the app has to take the data from the clipboard and add it to the corresponding controls within the items.

If the focus is on an editable control within an item, the control gets the data automatically.

Pasting via context menu does not work if a custom context menu is used.

View Settings

  • Provide individual buttons for each of the following settings on the toolbar of the grid list: sort, filter, group.
  • Clicking one of these buttons opens the view settings dialog or P13nDialog dialog with just the relevant page inside.
  • When closed, apply the settings to the grid list accordingly.

Keep the following in mind:

  • Do not offer any of these features if the grid list 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 on the toolbar of the grid list. Use the filter bar instead.
  • Always use only the view settings which are really needed. For example, do not offer grouping if it does not support your use case well.
  • Persist the view settings. When a user reopens the app, show the grid list with the same sort, filter, and group settings as last defined by this user.

Sort

  • For the default sort settings, sort by the item title, which is usually the identifier of an item.
  • If you offer sorting, offer it for each data point available in the item. Allow sorting in both directions, ascending and descending. The descending sort order must always be the exact reverse of the ascending sort order.
  • For each data point, provide a meaningful sort order. For example:
    • Sort text alphabetically
    • Sort numbers by their value
    • Sort status information by the severity of the status:
      • Ascending: Sort status information from positive to negative, with neutral last.
      • Descending: Sort status information from negative to positive, with neutral first.
      • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
      • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Filter

  • To display the current filter state, use the infobar below the title. Clicking the infobar opens the filter page of the corresponding dialog.
  • Show the infobar only if the filter settings are not shown somewhere else. For example, do not show the infobar for settings taken in the filter bar or in a select placed in the toolbar of the grid list.
  • If the infobar is shown, provide an option to reset all corresponding filters on the infobar.
  • Keep the infobar sticky (sap.m.GridList, property: sticky).
Developer Hint
To display the current filter settings on the infobar, consider using the list formatter (sap.ui.core.format.ListFormat).

Group

  • 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 data point]: [Grouping Value]
  • If there is no grouping value, show the following text:
    [Label of the grouped data point]: (Not Available)
    This is the case if you have a group of items that don’t have a value for the grouped data point.

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection,

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action, if it can be applied to all selected items.
  • Enable the action, if it can be applied to a part of the selected items. If the action is triggered, show a message that informs the user about how many items will be affected. Provide the choice to apply the action anyway or to cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element States.

If the action was applied, and if the items are still available, keep them selected.

Message for action which applies to a part of a selection
Message for action which applies to a part of a selection

To trigger actions that are independent of the selection, show the actions on the toolbar of the grid list. Examples of such actions are add, edit (in the sense of changing the whole table to edit mode), sort, filter, and group.

To trigger a default action on the whole item, use the “Active” or “DetailAndActive” list item type (sap.f.GridListItem, 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 Active 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.

Grid Lists in Object Pages

A grid list with up to 20 expected items can be displayed right away, without lazy loading.

If you expect the grid list to have more than 20 items, use one of the following 3 options:

  • Lazy loading (More button): Use this option if you expect to have up to 100 items.
  • Tab navigation: If you expect to have more than 50 to 100 items, but less than 400, use the object page with tab navigation instead of anchor navigation. Put the grid list on a dedicated tab.
  • Navigation to a list report: If you expect the grid list to have more than 400 items, or if the tab approach is unsuitable, restrict the number of items in the grid list itself to a reasonable amount. To provide the user with a way to work with the entire grid list, offer navigation to a separate list report containing all items.

For all of the three options mentioned above, we recommend providing a search, and if feasible, sort and filter capabilities for the grid list in the object page. Grouping should be avoided.

For more information on the use of grid lists within the object page, see Object Page – Tables.

Properties

sap.f.GridList

The following additional properties are available for the grid list:

  • The property: inset adds a margin on all sides of the grid list.
  • The property: headerText is a simple way to set the title for the grid list. However, this excludes the following:
    • A separate toolbar
    • variantManagement
  • 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 grid list.
  • The property: includeItemInSelection uses a click on the whole item to select the corresponding item if the grid list is in a selection mode. This competes with other settings like “Navigation” or “Active” and should therefore not be used in combination with these two settings.
  • 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 grid list is set to busy state)
  • The property: modeAnimationOn does not have any effect. Do not use it.
  • The property: showSeparators does not have any effect. Do not use this property.
  • The property: swipeDirection does not have any effect. Do not use this property.
  • The property: rememberSelections leaves items selected even if they are currently not 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 grid list to a busy state. While in busy state, the whole grid list 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 grid list has been set to this state. Use the default value.
  • The property: visible shows the grid list (“true”) or hides it (“false”).
  • The property: tooltip provides a tooltip for the whole grid list. Do not use it.

sap.f.GridListItem

The following additional properties are available for sap.m.ColumnListItem:

  • The property: selected allows an item to be selected programmatically.
  • The property: counter shows a number on the right side of an item. This is used in cases like showing the number of subitems.
  • 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 item. 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

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 for a master-detail scenario using the flexible column layout, as well as in popovers or dialogs. For certain use cases, lists can also be used in the dynamic page layout.

Usage

Use the list if:

  • You want to display a homogeneous set of basic data.
  • You need to sort, group, or filter simple datasets.
  • 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 datasets that need to be extensively sorted, grouped, filtered, or edited. In this case, use a table.
  • You work with complex hierarchies. In this case, 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, since they are usually used to navigate to the item details. For custom list items, you can also wrap the texts, 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 the preferable method for 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

Avoid empty lists. If necessary, provide instructions on how to fill the list with data (sap.m.List/ sap.m.ListBase, properties: noDataText, showNoData).

Examples:

  • If a list is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the list with data.
  • If a list is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    No filters set. To start, enter your search and filter settings and run the search.
  • If a list is used together with a filter bar and the filter does not return results, use the following text:
    No items found. Check the search and filter settings.

Adapt the texts above if:

  • The standard text is not precise enough for your use case (for example, no search is offered, only the search is offered).
  • You are using the live search (no Go button in the filter bar). In this case, leave out “run the search”.
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).
Empty list
Empty list

Count

List items can have a count, which is located on the far right of a row. You can use the count in simple lists, such as those that contain standard list items, to indicate how many subitems the user can expect when navigating to 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

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

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted items using status colors
Highlighted items using status colors
Highlighted items using indication colors
Highlighted items using indication colors

Behavior and Interaction

There are several ways to interact with the list and its list items:

List Level

Scroll

The height of the list is defined by the number of items it contains. It does not have its own scroll container, but is scrolled together with the app.

If the list 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 triggered by scrolling (preferred), or by clicking the More button.

When the user scrolls, the title and the filter infobar can stick to the top of the surrounding layout container (sap.m.List, property: sticky).

Information
The “sticky” feature comes with some limitations:

  • It is not available on all browsers. In non-supporting browsers, the corresponding areas are not fixed on top of the surrounding layout container while scrolling.
  • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the list is placed within the object page.
  • If the focus is set to a sticky area, the list is automatically scrolled to top.

Sticky title
Sticky title

Mode

The list can have several modes. The respective property (Mode) allows the following selection methods:

  • None
  • SingleSelectMaster (used to pick one item with no additional indicator, as in the master list for a master-detail scenario with the flexible column layout)
  • 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). The Shift key can be used to select a range.
  • Delete (used to delete items from the list using a delete indicator on the far right)
Developer Hint
In multiple selection mode, users can (de)select all items using the shortcut CTRL+A. This only affects items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded (for example, items added via lazy loading with growingScrollToLoad). This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

To process all items, listen to the selectionChange event and to its flag selectAll. This indicates whether CTRL+A was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

List with explicit single selection
List with explicit single selection
List with multiple selection
List with multiple 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

Line Item Level

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 pencil appears on the far right, indicating that something can be changed. The user can only click the pencil.)
  • Detail and active (same as “detail”, but the item itself is also clickable)

The example shows how all these types are visualized.

All list item types: inactive, detail, navigation, active, detail and active
All list item types: inactive, detail, navigation, active, detail and active

Indicate Navigated Item

When multi-selection is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case only (multi-selection list with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.ListItemBase, property: navigated).

Navigated item
Navigated item

Swipe

You can provide a swipe feature (sap.m.List, properties: swipeDirection, swipeContent) for approving or deleting items quickly without having to look at the details. Swiping is possible in both directions (left to right / right to left). You can provide different actions for each direction. Because swiping is only available on touch devices, only offer it as an additional feature. Swiping should never be the only way to perform the action.

List with swipe action
List with swipe action

Context Menu

The context menu can be triggered for the list or per item.

It gives users an alternative way of modifying the focused elements by giving access to context-specific functions.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or SHIFT+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

List - context menu
List - context menu

Drag and Drop

One or several items can be repositioned within a list or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop
Whole item as drop target
Whole item as drop target

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 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 without separators
List without separators

Guidelines

Text Length

When you use the list in the first column of the flexible column layout, keep the texts as short as possible and only as long as necessary. If you expect large numbers, use formatting instead.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the list. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning
The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

  • The number of rows in the table
  • The number of displayed columns
  • The complexity of the cell content (for example, simple text vs. complex charts)
  • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
  • The browser being used

Custom List Items

If none of the list items provided suits the requirements of your app, you can also create a custom list. If you choose this option, ensure that your custom list item is responsive when resized.

When creating custom list items, take the following guidelines into account, as needed:

Radio Button

Only use radio buttons if they are absolutely necessary. One example would be if you want to distinguish single selection from navigation. This is a rare case in which visible radio buttons for single selection are allowed.

Actions

To trigger actions on single items, show the actions on a toolbar above the list. Do not offer actions on multiple items if the list is expected to have fewer than 10 items in most cases.

The following actions on single items must always be inline:

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

You can combine delete and edit actions, or delete and navigation actions. However, edit and navigation actions cannot be combined.

To trigger actions that are independent of the selection, show the actions on a toolbar above the list. For example: AddCollapse AllExpand 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). When clicked, active items trigger an event that can be handled by the app (for example, to open a dialog). Selection of items and expanding/collapsing a node do not trigger the event, and are handled by the tree. Do not use the active item type 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 the single selection master.

Add Items

For adding items, place an Add or Create text button on the table toolbar.

  • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
  • Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the table, with a visual highlight at the beginning of the row.

For more information, see the guidelines for managing objects (including subarticles).

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Let users choose whether to apply the action anyway or cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element – States.

If the action was applied and the items are still available, keep them selected.

Message for action which applies to a part of a selection
Message for action which applies to a part of a selection

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, it is not accessible, since there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.

Use drag and drop only in addition to existing visible UI elements
Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within the list, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop targets in between items
Drop targets in between items

Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on values, the dropped item needs to take on the corresponding value of the target group. If this is not wanted, do not allow users to rearrange items in grouped lists.

 

Example:

A list is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Don't
Do not combine rearranging items with grouping, unless you know exactly what you're doing
Do not combine rearranging items with grouping, unless you know exactly what you're doing

Export to Spreadsheet

Apps can provide a menu button for exporting list data to a spreadsheet (for example, on the relevant toolbar). For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button
'Export to Spreadsheet' menu button

Resources

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

Elements and Controls

Implementation

Upload Collection

Information

The Remove/Close icons shown in this article do not yet reflect the new Remove/Close icon    defined in the product standard for UX consistency. We will update this article as soon as the new icon is available in the corresponding controls.

Information
The upload collection replaces the deprecated sap.ca.ui.FileUpload control. Please refrain from using the old CA control.

Intro

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.

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 L
Upload collection – Size L

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

If empty, the upload collection provides users with a hint that they can use the Add button or drag and drop to upload files. This hint already provides a large enough zone for users to drop their files.

Developer Hint
Applications should not use self-built placeholder items to tell users that there are no files to display, since they would override this hint.
Interaction – Upload collection empty
Interaction – Upload collection empty

Using the Add Button

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 – Add
Interaction – Add

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 in progress
Interaction – Upload in progress

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.

Using Drag and Drop

Users can easily select one or multiple files from their computer and drag them onto the upload collection to start the upload.

As soon as users start to drag a file over the application, the hint changes into a drop zone informing users where to place the file.

Interaction – Drag and drop - Start
Interaction – Drag and drop - Start

When the file is over the drop zone, it changes again to tell users that they can release the file.

The uploading process itself is the same as if a file had been added via the Add button.

Interaction – Drag and drop - Before drop
Interaction – Drag and drop - Before drop

Opening Files

The user can click 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 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: Rename 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 somewhere outside the input field to change the focus.
  • The user clicks Rename.
  • The user presses ENTER.

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.

Important: Make sure that you trigger this dialog via the standard Edit button that is provided for each item.

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 an edit dialog
Interaction – Example of an edit dialog

Deleting Files

The delete function works identically on desktop and mobile devices.

As soon as the user clicks 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 and contact data, or the version history of a file. Use a quick view to show this additional information.

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.

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 infobar if a filter is set. The sorting criteria should not be displayed in the infobar.

Clicking the infobar 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 infobar 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.

The user types in a name that is identical to one that already exists.

When the user clicks Rename or tries to remove the focus from the input field, the field is highlighted (semantic color: error).

Placing the focus back on the field shows the error message (form field validation).

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 Close button cancels the entire upload process.

Interaction – Upload duplicate – Details
Interaction – Upload duplicate – Details

Folder Structure

The upload collection control can display hierarchical folder structures containing files, similar to an operation system’s file browser or popular cloud storage services.

Info: Renaming and deleting folders works the same way as it does with files and will therefore not be covered in this section. For more details, check the respective sections on renaming and deleting files.

While files are represented by individual icons that correspond to the file’s MIME type, all folders are represented by the same icon (  ) since their contents may vary.

Instead of the regular title, use breadcrumbs to enable users to see which hierarchy level they are on, and to provide an easy way to navigate back to any previous step.

In the item counter after the breadcrumb, show the sum of all items in the current folder, counting both folders and files.

Folder Structure (1)
Folder Structure (1)

When the user clicks a folder, the current list is replaced by the contents of that folder. Note that the breadcrumb needs to be updated to show the previous folder as well as both the name of the current folder and number of items it contains.

Folder Structure (2)
Folder Structure (2)

The same behavior repeats as the user navigates deeper: the previous folder name is converted to a link, while the current folder is appended to the breadcrumb and both the counter and the list are updated.

Folder Structure (3)
Folder Structure (3)

If users are allowed to create their own folders, provide a custom action button in the toolbar called New Folder. With this button, trigger a dialog prompting users to enter a name for the new folder.

After confirmation, the new folder is created on the same hierarchy level that is currently visible in the upload list.

Folder structure – Dialog for creating a folder
Folder structure – Dialog for creating a folder

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. The separators make it easier for users to scan 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

Placeholder Items

Applications should not use self-built placeholder items to tell users if there are no files to display. This information is provided automatically by the control.

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

Visual Filter Bar

Information
The Remove/Close icons shown in this article do not yet reflect the new Remove/Close icon    defined in the product standard for UX consistency. We will update this article as soon as the new icon is available in the corresponding controls.

Intro

The visual filter bar offers a unique way of filtering large datasets through visualizations. This helps users to recognize facts and situations, while reducing the number of interaction steps needed to gain insights or to identify significant single instances.

The visual filter bar allows users to combine measures with filter values. For example, a “Product” might have the filter value “Product Name” and the measure might typically be “Revenue”, “Cost”, or “Quantity”. If you opt for the measure “Revenue”, the chart would show the “Revenue by Product”, enabling the user to filter the data by choosing a particular product name and its revenue.

Chart visualization increases the joy of use and helps users to see relevant data more quickly. For filtering, the visual filter bar uses all of the three types of interactive chartbar chartline chart and donut chart.

Visual filter bar - Size L
Visual filter bar - Size L

Usage

Use the visual filter bar if:

  • You are using analytical list page floorplan.
  • Users need to see both the result and the direct impact of their filter settings in a chart representation.
  • You would like to give users a condensed overview of the data in the dataset.

Do not use the visual filter bar if:

  • You are not using the analytical list page floorplan.
  • Users are not interested in seeing the impact or their filter settings directly in a chart representation.
  • Users are not interested in a condensed overview of the data in the dataset.

Responsiveness

The visual filter bar itself is fully responsive. For overall responsiveness within the analytical list page, see the Analytical List Page article.

Layout

The visual filter bar is a composite control built with other responsive controls, such as the header container and the interactive charts. It is used in the header area of the analytical list page, which incorporates the dynamic page layout.

Collapsed Visual Filter Bar

The collapsed visual filter bar takes up less space, leaving most of the screen for displaying 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 the header. If required by the use case, you can expand the filter bar by default.

On desktop and tablet devices, the collapsed filter bar shows a summary of the filters currently applied. The format of the summary text is:

Filtered By (number of filters): <comma-separated list of the filters currently applied>
Example: Filtered By (2): Country/Region, Product

Up to 5 filters are listed. If more filters have been applied, an ellipsis (…) appears at the end of the string. If no filters have been applied, the summary text is Not Filtered.

Expanded Visual Filter Bar

The expanded visual filter bar also shows a user-defined filter subset of the selected variant. The Adapt Filters link opens the visual filter dialog, where the user can add or hide visual filters. The switch button on the top right switches between the visual filter bar and the standard (input-based) filter bar. The Go button triggers the filter. Note that the Go button is only shown in manual update mode.

Structure

In order to achieve filtering through visualization, the visual filter bar uses interactive charts. Currently, three interactive chart types are available: bar chartline chart, and donut chart. Each chart has a dedicated area for the chart title, the (x) link showing the number of applied filters, and the value help icon  . When the user clicks the (x) link, a popover containing the selected filter values appears. The value help icon opens a value help dialog.

Filter Title Area

In addition to the chart title, the filter title area also contains a value help icon  with (x) indicator, where “x” stands for the number of applied filters. Clicking the icon opens the value help dialog. The value help dialog can be replaced with the select popover icon  .

Use the following naming convention for the filter title, using title case: <Measure Name> by <Dimension Name> | <Scale Factor> <Unit of Measure>. For example, Project Costs by Project | K EUR, Sales Volume by Commodity | M PC.

Visual filter bar - Title area
Visual filter bar - Title area
Visual filter bar - Title area with selected filter values
Visual filter bar - Title area with selected filter values

Bar Chart

The interactive bar chart in the visual filter bar can display only three bars. Based on the measure, they can be sorted ascending or descending. This makes it easy to compare the items and see the highest and lowest values.

Visual filter bar - Interactive bar chart
Visual filter bar - Interactive bar chart

Line Chart

The interactive line chart is used to display variations over a specified period of time. This chart is only used for displaying a time series and can contain only the first or last six time points (for example, last six days, last six months, and so on). 

Do not use a line chart to show categories. Instead, use a bar chart.

Visual filter bar - Interactive line chart
Visual filter bar - Interactive line chart

Donut Chart

The interactive donut chart is best used to display up to three slices. Use this chart if the exact value of each slice is not needed for filtering.

In the visual filter bar, only the top or bottom two values are shown; the rest are aggregated into the Other section.

Visual filter bar - Interactive donut chart
Visual filter bar - Interactive donut chart

Visual Filter Selections

Any data point or segment selected in a chart remains selected when the user changes the measure, chart type, or sort order in any of the charts.

If a selected record falls outside the top or bottom three records being displayed, the (x) status above the chart shows the number of selected records.

Developer Hint

Do not bind a single visual filter (chart) to more than one ID. This will lead to an incorrectly derived item count in the (x) link. Define separate visual filters instead. If this split is not desired, create a calculated column (dimension) in the back end to represent this combined ID.

Don't
Don't use a relative format for time
Don't use a relative format for time
Do
Use titles that give context
Use titles that give context
Do
Add the year in the title if you display only 4 quarters
Add the year in the title if you display only 4 quarters

Visual Filter Dialog

The filter dialog is launched by clicking the Adapt Filters (number of applied filters) link in the upper right filter area. In the filter dialog for visual filters, the user can choose which filter fields are shown in the visual filter bar.

In this dialog, the user can make the following changes:

  • Add visual filters
  • Delete visual filters
  • Hide visual filters in the visual filter bar
  • Search for visual filters
  • Change the sort order of each visual filter
  • Change the chart type of each visual filter
  • Switch to other measures in the visual filter display

The footer toolbar at the bottom of the dialog provides the following functions:

  • Save: Saves your modified filter set variant. 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 use case.
  • Go: Applies the selected filter set.
  • Clear (optional): Clears all filters. Only use this button if it fits the app use case.
Visual filter dialog
Visual filter dialog

Visual Filter Configuration

In the filter dialog, users can configure individual visual filters using the icons in the filter title area:

  • Change the sort order   (not supported for line charts)
  • Switch to a different chart type  
  • Choose between different measures
Visual filter configuration - Sort, chart type, measure
Visual filter configuration - Sort, chart type, measure

Behavior and Interaction

Unlike micro charts, the charts in the visual filter bar are interactive. If you are using live update mode, selecting a filter value triggers data filtering in the content area. Both single and multiple selection are supported.

Selecting Filters

In the visual filter, you can make a selection by clicking a chart value. To deselect it, you can either click the same value in the chart again, or click the (x) link showing the number of selected filters, such as (1).

Any data point selected in a chart remains selected, even if the user selects a data point in another chart. Filter values also react to each other.

If a selected record in a chart falls outside the displayed filter values, the selection is visible in the (x) link above the chart, where (x) represents the number of selected records.

Users can select more filter values with the value help or select popover.

Personalizing the Visual Filter Bar

Add Visual Filter

Users can add more visual filters via the visual filter dialog. The additional filter groups appear below the Basic filter group, which contains the standard filters for the application. While the Basic filter group is always visible, the additional filter groups are initially collapsed.

The More (x) link in the filter group header indicates the number of filters that have not yet been added, for example More (2). Clicking this link opens a dialog for selecting the additional filter. Once a filter has been selected, it displays under the group header in the visual filter dialog, and the user can customize the individual filter settings (sort order, chart type, measure, display in the visual filter bar).

If all filters in a group have already been added in the visual filter dialog, the More (x) link label in the filter group title switches to Change Filters.

Hide Visual Filter

Users can hide a filter 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

Live Update / Manual Update

The visual filter bar is available in two modes: live update and manual update. In both modes the visual filter charts refresh based on the selection.

Live Update

In live update mode, the filter bar reacts instantly to every input change. Because the content area updates automatically whenever the user changes a filter selection, the Go button is not necessary, and is not shown.

Visual filter bar - Live update mode
Visual filter bar - Live update mode

Manual Update

In manual update mode, the filter results are only updated when the user clicks the Go button that is shown in manual mode. Pressing ENTER on the keyboard also triggers the filter.

Visual filter bar - Manual update mode
Visual filter bar - Manual update mode

Recommendation 

In general, use live update mode, which is more convenient for users. However, consider using manual update mode if the user has to configure multiple filters to obtain a useful result set, or if you expect the resulting traffic to be excessively high.

Chart Types

Choosing the right chart type as a representation for a particular filter will not only increase the joy of use but also will convey the right information to the user. Inappropriate chart types can mislead the user during the filtering process.

In the visual filter bar, you can choose between three interactive chartsbar chartline chart, and donut chart.

Recommendation

  • If you expect users to be working with a large number of datasets, and your scenario does not depict time periods, consider using a bar chart.
  • If you want to measure trends and changes over time when filtering, consider using the line chart.
  • If your scenario requires filtering by parts of a whole and has only a small number of datasets, consider using the donut chart.

Filter Selection

In the visual filter, users can make a selection by clicking a chart value or by using the value help to select data points that are not visible. Depending on the number of available data points, you can use the value help or the select popover.

Recommendation

If your scenario involves filtering 200 or more filter values, consider using the value help. For filtering less than 200 values, we recommend using the select popover.

Scaling Factor

Always use a scaling factor to display values larger than 1000. The scaling factor is usually displayed in the interactive chart header. Do not repeat the scaling factor inside the chart itself.

Recommendation

Due to the limited space inside the chart, we recommend showing a maximum of 3 digits before the decimal point.

Visual filter bar with scaling factor (M)
Visual filter bar with scaling factor (M)

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.

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.

Actions and Layout

Actions can be used as follows:

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

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

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

Responsiveness

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

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

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

Responsive toolbar – Size L
Responsive toolbar – Size L
Responsive toolbar – Size S
Responsive toolbar – Size S

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. The  “” (overflow) button is a toggle button and can be used to switch the overflow menu on and off.

The user clicks the overflow button to open a popover. In this action sheet, all icon buttons are labeled with text. Overflow is supported for the following controls:

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.

The sap.m.ToolbarSeparator can also go into the overflow. The separator then changes from a vertical line into a horizontal line. If the control happens to be the first or the last item of the overflow area, the separator isn’t displayed.

Prioritization

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

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

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

Grouping

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

Table toolbar on desktop without overflow
Table toolbar on 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

Header and Footer Toolbars

Use the following button styles for the different action types in the header and footer toolbars:

  • Primary action: Use the emphasized button style.
  • Secondary action: Use the ghost button style. Note that the ghost button has a transparent background.
  • Semantic action: Use the semantic buttons for positive and negative actions. Use the “accept” style for positive actions, and the “reject” one for negative actions. Semantic actions must always be text buttons.
  • Negative path action: Use the transparent button style.

Do not use any other style types.

Content Toolbars

Use the following button styles for the different action types in content toolbars (for example, in tables, forms, or charts):

  • Primary action: Use the emphasized button style. Usually, the primary action is positioned in the header or footer toolbar. Note that there can only be one primary action per page. If a page already has a primary action, but you also need to highlight the most important action in a content toolbar, use the ghost style for this one button in the content toolbar.
  • Secondary action: Use the transparent button style.

The different button styles are designed to give appropriate feedback to users. Do not use them for decoration purposes.

Button with different styles
Button with different styles

Styles and Toolbars

Apply the following menu button styles for the different toolbars:

  • Header and footer toolbars: Use the ghost style.
  • Content toolbars: Use the transparent button style.

Do not use any other style types.

Emphasized and Semantic Buttons

  • Use a maximum of 1 emphasized button per toolbar.
  • Never mix emphasized and semantic buttons.
  • Ideally, there should be only one emphasized action per page. There can be valid exceptions, but we generally recommend using only one emphasized button.
  • For more information, see Buttons.

Enumeration

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

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

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

Types

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

  • Header toolbar: Contains global actions that are important for the whole page
  • Footer toolbar: Contains only closing and finalizing actions
  • Table toolbar: Toolbar that is positioned above a table and contains table-specific actions
  • Chart toolbar: Toolbar that is positioned above a chart and contains chart-specific actions
  • Infobar: Toolbar that indicates what filters have been set, and how many items have been selected
  • Tree toolbar: Toolbar that appears above a tree or tree table, and is used for actions that impact the entire tree.

Header toolbar with primary action (emphasized style) and secondary actions (ghost style)
Header toolbar with primary action (emphasized style) and secondary actions (ghost style)

Footer toolbar with standard actions: 'Save' (emphasized) and 'Cancel' (transparent)
Footer toolbar with standard actions: 'Save' (emphasized) and 'Cancel' (transparent)

Table toolbar with search field, text buttons (ghost and transparent style), icon buttons (transparent style), and segmented button
Table toolbar with search field, text buttons (ghost and transparent style), icon buttons (transparent style), and segmented button

Chart toolbar
Chart toolbar

Inactive infobar (not clickable)
Inactive infobar (not clickable)
Active infobar (clickable)
Active infobar (clickable)

Tree toolbar
Tree toolbar

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.
  • Place semantic buttons side by side (for example, Accept and Reject).
  • 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.
  • Do not use icon buttons for app-specific actions (neither icon-only buttons, nor icon+text buttons).
  • 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

Micro Process Flow

Intro

The micro process flow control enables you to visualize the state of individual items in a linear workflow. You can embed it into a list or a table.

Micro process flows
Micro process flows

Usage

Use the micro process flow if:

  • You need to show the state of each step in a linear, multi-step process.
  • Users need to see the progress of multiple items displayed in a list or table at a glance.

Do not use the micro process flow if:

Responsiveness

The micro process flow is responsive and adapts to the size of its parent container. If the micro process flow is too long for the parent container’s width, you can choose how it should behave:

  • Simple wrap: Steps that don’t fit into the width of the parent container wrap to a new line.
Simple wrap behaviour of micro process flow
Simple wrap behaviour of micro process flow
  • Overflow: Navigation arrows appear on both sides of the micro process flow, with the number of hidden steps indicated next to each arrow. By clicking the navigation arrows, users can scroll horizontally through all of the steps in the micro process flow.
Overflow behaviour of micro process flow
Overflow behaviour of micro process flow

The micro process flow control supports cozy and compact form factors.

Layout

The micro process flow acts as a generic container in which process steps are laid out linearly along the horizontal axis. The control provides the following layout options:

Default

The process steps appear as icons with a circular background. They use semantic colors and provide click events. You can choose from different icons provided by the SAP icon font.

Guidelines
Always replace the default icons with icons that fit to your use case.
Default layout with a circular background
Default layout with a circular background

Custom

The default steps can be replaced by other controls. The following controls are supported:

Guidelines
Make sure that you replace the default tooltip texts from the original icons or controls with the names of individual steps in the process. For example, Payment, Shipping, Delivery. For more information, see Using Tooltips.
Custom layout using the 'status indicator' control
Custom layout using the 'status indicator' control
Custom layout using the 'micro chart' control
Custom layout using the 'micro chart' control

Types

There are two micro process flow types: one with dependent steps and one with independent steps.

Dependent Steps (Default)

The dependent steps come with a connector line that appears between the process step and the step that follows it. Use this type when the completion of a step is a precondition for the subsequent step.

Guidelines
When customizing the width of the connector lines, the minimum width must not be less than the default width, and the maximum width must not exceed the step width or step height (whichever is greater).
Micro process flow with dependent steps
Micro process flow with dependent steps

You can also indicate the state of the transition between two steps with a suitable icon.

Guidelines
The width of the icon must not exceed 60% of the connector line width. The height of the icon must not exceed the size of the step node.
Micro process flow with transition state
Micro process flow with transition state

Independent Steps

Independent steps are not connected and can be processed in any order. Use this type when the user doesn’t need to perform the steps in a linear sequence.

Micro process flow with independent steps
Micro process flow with independent steps

Guidelines

Popover with Step Details

Users often need more information about a step. To provide more details, add an on-click popover for each step. Also add a click event for each step to invoke the popover.

Micro process flow with on-click popover
Micro process flow with on-click popover

Exchange Default Icons

Always exchange the default icons and replace them with icons that best fit your use case and line of business.

Do
Use case-specific icons
Use case-specific icons
Don't
Former default icons
Former default icons

Resources

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

Elements and Controls

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 planning calendar can also be used without a row header. In this case, the row header disappears and only the appointments are visible. It can be used to show the calendar of one object. Note that the control was built mainly to compare time slots of different objects. For this reason, the time axis is shown horizontally and, depending on the interval, the appointments might shrink to smaller size. In this case, the text is cut off rather than truncated.

Components

This section describes the various components of the planning calendar.

Parts of the planning calendar
Parts of the planning calendar

The control consists of different parts:

  1. Header
  2. Toolbar
  3. View switch
  4. Navigation
  5. Time strip for hours/days/months
  6. Row header
  7. Row
  8. List item
  9. Interval appointment
  10. Appointment

1. Header

The header contains the toolbar and the navigation.

2. Toolbar

The toolbar consists of the calendar title (optional) and the toolbar actions, including a default view switch. You can add generic and app-specific actions that are relevant for your use case (such as creating an appointment, search, settings, showing the calendar legend, and so on). Always place actions that affect the entire calendar in the toolbar.

For more information, check out the toolbar guideline article.

The generic actions are as follows:

Search
Create Appointment
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)

3. View switch

The view switch allows the user to switch between different time intervals (calendar views). Depending on the number of available calendar views, the view switch can be a segmented button (four views or less) or a select control (five views or more).

The default calendar views are Hours, Days, Months, 1 Week, and 1 Month. The app developer can choose which views to include, depending on the use case, and how many values are shown for each view. App developers can change the default number of values shown, but they should then ensure that the app is still responsive. The app developer can also create custom views.

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

The 1 Month view shows an entire month. On desktop devices, 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.

4. Navigation

The navigation area contains back and forward arrows, the Today button, a date interval link, and the time strip. Clicking the Today button takes the user to the period containing the current day. Clicking the date opens a date picker for direct navigation.

5. Time strip for hours/days/months

The time strip reflects the selected view, and shows the hours, days or months that are currently visible. In all views that show days (Days, 1 Week, 1 Month), you can display calendar weeks in an additional line below the time strip (property: showWeekNumbers).

6. Row header

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

You can also add an action on the row header (event: rowHeaderClick).

7. Row

The row contains all appointments for an object. You can turn the alternating row coloring on or off. By default, the alternating rows option is turned on.

8. List item

The list item contains the row header, row, appointments, and interval appointments. Each row can show different working and non-working days.

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

9. Interval appointment

Each row can also have interval appointments, which differ from half-sized appointments visually and in that they are always at the top of the row. Interval appointments can be used to show appointments that last for a longer period of time, such as vacations or workshops.

You can opt to hide the space reserved for interval appointments if no such appointments exist for that time period.

10. Appointment

Appointments consist of an icon or picture, a title, and a subtitle. Concurrent appointments are shown one above the other. There are two appointment sizes – regular and half size. Half-sized appointments save space, but don’t show a second line with appointment details.

You can define the colors for different appointment types. Appointments can also be set to tentative.

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

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

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

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

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

Planning Calendar Legend

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

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

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

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

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

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

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

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

Planning calendar legend
Planning calendar legend
Developer Hint
To prevent waiting time, app developers should load the sap.ui.unified library.

Behavior and Interaction

To create an appointment, the user must trigger an action by clicking the Create button in the toolbar. You can also configure the control to create a new appointment when the user clicks directly on a row.

The user can click the appointment to see further details. The app development team must define what kind of information is then shown. For example, clicking 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 visible interval, appointments might be smaller and the text cut off. The user can click the appointment to see the details.

View switch

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

Today

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

Back and forward navigation

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

Date picker

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

Snapping Header

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

Header snaps to top when scrolling down
Header snaps to top when scrolling down

Drag and Drop

Drag and drop can be used to move appointments (to enable Drag and Drop use property: enableAppointmentDragAndDrop). Moving an appointment automatically changes its start and end times (for example, if an appointment is scheduled from 1:00-2:00 PM, the user can drag it and change the time from 2:00-3:00 PM) . When dragged, the appointment is shown as a ghost element on the mouse cursor. Drop target areas are indicated to the user with a placeholder.

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

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

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

Combined appointments and interval appointments are not draggable.

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop

Guidelines

Switching the Row Header

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

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

Our guideline is to use the select control in the place of the calendar title. The select control will contain all the attributes that can serve as the row header. When a different attribute is selected, the calendar is rearranged accordingly. You can also add a counter after the list items to indicate how many appointments fall into a specific group.

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

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

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

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 boxmulti-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 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 clicking the relevant tokens.

The user can select a series of tokens by placing the cursor in an initial position (which can also be a token), holding down the SHIFT key, and clicking a new position. The tokens between these two cursor positions are then selected.

Adding Tokens

The user can add tokens to the multi-combo box and multi-input control. New tokens are added in the order in which they are entered.

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

Removing Tokens

The user can instantly remove tokens via the keyboard, or by clicking the Remove  icon.

Styles

There are five different styles of tokens: regularon 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

Variant Management

Intro

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

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

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

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

Information
Note on terminology:

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

Usage

Use the variant management control if:

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

Responsiveness

Size S (Smartphone)

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

My Views
My Views
Manage Views
Manage Views
Save View
Save View

Size M (Tablet)

My Views
My Views
Manage Views
Manage Views
Save View
Save View

Size L (Desktop)

My Views
My Views
Manage Views
Manage Views
Save View
Save View

Components

Variant management come with several components:

  • A clickable title with an icon
  • The My Views dialog for selecting variants
  • The Manage Views dialog for setting view parameters and deleting views
  • The Save View dialog for creating a new view

Name of View

The view name is the entry point for opening the My ViewsManage Views, and Save View dialogs.

If the user has made changes to the user interface that affect the saved view, the view is marked with an asterisk (*) to indicate the unsaved changes. This happens when the user deletes or adds a filter to the filter bar, for example.

Selecting a view
Selecting a view

My Views Dialog

The My Views dialog contains all favorite views, including the default view, the pre-shipped standard views, and the views marked as favorites by the user. The default view and the pre-shipped standard views are marked as favorites automatically.

Default View

There can only be one default view, which the user can change in the Manage Views dialog. If the user sets a new default view, the last view remains as a favorite. The user can explicitly unfavorite the last view in the Manage Views dialog.

Pre-Shipped Standard Views

The standard view is the minimum set of filters delivered by SAP, and cannot be modified or deleted. It is flagged as a favorite and cannot be removed. There can be several pre-shipped standard views, depending on the use case.

Favorite Views

Users can mark views as favorites (or unfavorite them) in the Manage Views dialog. If more than 10 favorite views exist, a search option is displayed.

The views created by users themselves are favorited automatically, while views created by other users are unfavorited by default. This prevents the My Views popover from becoming overcrowded with public variants that are not relevant for the user.

The user can also mark public views as favourites.

Public Views

Public views are visible to all users who have access to the app. A view can be set to Public by individual users, key users, SAP (default delivery), or partners. All views that are set to Public are available within the Manage Views dialog.

A public view can be edited by the user who created it and by key users. All other users can only display the public view.

Actions in the My Views Dialog

Users can open the Manage Views dialog using the Manage button in the footer bar of the My Views dialog. From this dialog, users can Save changes to the current view, or choose Save As to create a new view, which opens the Save View dialog.

'My Views' dialog with a few views
'My Views' dialog with a few views
'My Views' dialog with more than 10 views and a search option
'My Views' dialog with more than 10 views and a search option

Manage Views Dialog

In the Manage Views dialog, users can make the following changes:

  • Mark a view as a favorite
  • Change the name of a self-created view
  • Set a view as the default
  • Apply the view automatically
  • View the Sharing and Created By information of each view
  • Delete a self-created view

In addition to the personal views users create for themselves, they can also see the pre-shipped and public views. A user can only modify his or her own views, and not public, pre-shipped, or third-party views created by other users. 
Exception: Key users can also change and delete views created by others.

'Manage Views' dialog
'Manage Views' dialog

Save View Dialog

The Save View dialog is for creating a new view. For each view, you can make the following settings:

  • View: Name of the new view (required field)
  • Set as Default: If checked, the new view is the new default view.
  • Public: If checked, the new view is available to everyone who has access to the app.
  • Apply Automatically: If checked, the view is applied immediately whenever it is selected. The user does not need to click the Go button in the filter bar.
    We do not recommend checking this option if the selection is likely to cause long loading times.
'Save View' dialog
'Save View' dialog

Layout

The variant management control is merged with the page title (or next to or merged with title of the respective control, such as a table).

Filter Bar (Page Title)

The variant management control is merged with the page title within the page header container, and saves the stored filter settings or both the filter and control settings.

Variant management within the filter bar, merged with the page title
Variant management within the filter bar, merged with the page title

Table

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

It is either merged with the control title or placed next to it.

If you place the title or variant management control inside a toolbar, apply the following styles:

  • Set the toolbar height to 3 rem.
  • Use a transparent toolbar.
  • Use the title class “sapMH4Fontsize”.
Variant management within the table toolbar
Variant management within the 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 for filter settings and control parameters such as layout, table column visibility, sorting and grouping.

My Views dialog: Selecting a View

The page title displays the active variant. Clicking the title dropdown opens a popover that displays all available variants. The currently active variant is highlighted. To load another variant, the user simply selects one from the list.

Save

Save can only be applied to variants that the user is allowed to save. Otherwise, this button is disabled. Save overwrites the active variant.

Save As

Save As enables the user to save the current filter settings as a new view. The Save As function can also be used to duplicate existing variants for later modification.

Manage

Manage opens the Manage Views dialog that allows the user to update, delete or favorite/unfavorite existing variants.

Selecting a view
Selecting a view

Save View dialog

The Save View dialog is for creating new views. Providing a name for the new view is mandatory. Clicking OK saves the new view.

Save View
Save View

Manage Views dialog

In the Manage Views dialog, the user can rename, delete, and change properties of existing views.

Users can only modify or delete entries if they have the necessary permissions. By default, variants that a user has created can also be modified and deleted.

Manage Views
Manage Views

Save as Tile

The user can save the currently selected variant as a tile on the launchpad using the Save as Tile action in the Share menu.

In the Save as Tile dialog, the user can define the tile title and subtitle, a description, and the launchpad group in which the tile should appear.

Save as tile via 'Share' button
Save as tile via 'Share' button
'Save as Tile' dialog
'Save as Tile' dialog

Guidelines

Save as Tile

Use the name of a variant as the title of the application tile. Map this as a preset title that cannot be edited by the user.  In this case, whenever the variant is updated, the tile is updated accordingly.

Exception: If the variant cannot be referenced directly due to technical limitations, offer the standard tile creation option where filter parameters and settings are only saved within the URL.

Resources

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

Elements and Controls

Implementation

Value Help Dialog

Intro

The value help dialog is a UI pattern that helps the user find and select single and multiple values. The user can also define and select multiple ranges. The value help dialog is generally called from an input field or a multi-input field by clicking the selection icon (value help icon) of the input field.

Usage

Use the value help dialog if:

  • The user needs to use different attributes (such as city, company name, and so on) to find an object.
  • The user is searching within a dataset containing more than 200 items.
  • The user needs to define and select ranges and exclusions.

Do not use the value help dialog if:

  • There is a simpler control that fits the use case. Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). For more information on when to use which control, see Selection Controls – Overview.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

The behavior of the value help dialog on a phone differs from its behavior on a tablet or desktop device. Both the navigation and the positioning of the selection area differ depending on the device.

Value help dialog - Size S
Value help dialog - Size S
Value help dialog - Size M
Value help dialog - Size M
Value help dialog - Size L
Value help dialog - Size L

Components

The value help dialog contains the following components:

1) Header bar
2) Icon tab bar / list control (phone)
3) Search template (optional)
4) Basic search
5) Advanced search
6) Result list
7) Items row (selected items, excluded items)
8) Footer toolbar
9) Include/exclude areas for range selection

Header Bar (1)

The header bar contains the dialog title. For guidelines on the dialog title, see the Guidelines section of this article.

Icon Tab Bar on Tablet/Desktop and List Control on Phone (2)

Depending on the device, the following controls are used to display the content of the value help dialog:

  • Smartphones: The start dialog provides a list (sap.m.List) with the standard list items (sap.m.StandardListItemSelect from List and
    Define Conditions to navigate between the different dialogs.
  • Tablet and desktop devices: The value help dialog contains an icon tab bar (sap.m.IconTabBar) to navigate between the Select from List and the Define Conditions tab.

Search Template (3)

Search templates allow the user to display different or additional fields in the advanced search field and the results list. Depending on the use case, the user can switch between the different search templates in order to use different fields when searching. For example, the search template “Customer (by company code)” displays the additional field “Company code” in the advanced search and result list.

Basic Search (4)

The basic search finds all results that are somehow related to the input. For example, the search term “A” returns all the results containing the letter “A”.

Always offer the basic search in the value help dialog. Position the basic search to the right of the search template control. If there is no search template control, left-align the basic search.

Advanced Search (5)

The advanced search offers a search field for each column in the result list.

Value help dialog - Advanced search
Value help dialog - Advanced search

For implementation of the basic and advanced search, the filter bar (sap.ui.comp.filterbar.FilterBar) is used in advanced mode. Advanced mode differs from basic mode in the following ways:

  • There is no Filters link or a dialog to make additional filter fields visible. All filter fields/advanced search fields are added automatically to the advanced search area.
  • There is a toggle link to show and hide the advanced search.
  • In each of the filter fields, users can use operators like “between” or “lower than” to define ranges.

Always collapse the advanced search by default.

Note that the value help icon of the business object ID field and description field for the business object that opened the current value help dialog will open only the Define Conditions screen. The entire value help dialog is not shown in order to prevent endless loops. For example, the value help icon of the customer ID or description field in a Select: Customer value help dialog will navigate directly to the Define Conditions screen.

How the Advanced Search Works

The user can include operators (such as “=“) to define the ranges directly within the field without moving to the fields of the Define Conditions tab.

The user must type the following to get results:

Operator Input Notation Example
between valuevalue 000100
equal to =value =0001
contains *value* *1*
starts with value* 001*
ends with *value *5
less than <value <100
less than or equal to <=value <=200
greater than >value >0300
greater than or equal to >=value >=0500
not equal to* !(=value) !(=0)

* Note that there isn’t an explicit “not equal to” operator. Instead, you need to use “Exclude” (!) in conjunction with the “equal to” operator (=).

Advanced search using operator
Advanced search using operator

Result List (6)

  • You can prefill the result list of the value help dialog by default.
  • If you transferred values from the input field to the basic search field of the value help dialog, the results are filtered accordingly.
  • If available, display the ID and description of the business object in the first and second columns. Display additional information in the next columns.
  • We recommend a maximum of five columns in the results list.

Selected/Excluded Items Row (7)

The row for Selected Items / Excluded Items is displayed in the panel container (see panel for more information). Each item or range that is selected or excluded is displayed as a token in the selected or excluded item row.

  • On desktops, the selection area with the selected and excluded items row is initially expanded.
  • On tablets and phones, the selection area with the selected and excluded item row is initially collapsed.

Footer Toolbar (8)

The footer bar offers the OK and Cancel buttons.

Include/Exclude Areas for Range Selection (9)

In the Include and Exclude areas of the Define Conditions tab, you can define single and multiple ranges with the following operators:

  • equal to
  • between
  • less than
  • less than or equal to
  • greater than
  • greater than or equal to

Each range is displayed as a token in the selected or excluded item row.

Developer Hint
For information on how to manage white space characters (blanks) when users copy and paste text into input controls, see Removing Leading and Trailing White Space.

Behavior and Interaction

Basic and Advanced Search

  • The basic search (mandatory) and advanced search (optional) are triggered by clicking the Go button. The search results are shown in the result list.
  • If the input field where the user is coming from contains data, this data is transferred to the basic search of the value help dialog and the results are then filtered accordingly.
  • The basic search performs a search across all fields that are displayed in the advanced search and the result list.

Item and Range Selection

Depending on your use case, the value help dialog can offer different selection options:

  • Select a single item
  • Select a single range
  • Select multiple items
  • Select/exclude multiple ranges

Users open the value help dialog by clicking the value help icon of the input field. The next steps depend on the use case and form factor (smartphone or desktop/tablet).

The different use cases are described in the sections below.

Select a Single Item (Smartphone)

Tapping the value help icon opens the Select from List tab. As soon as an item is selected, the value help dialog closes automatically.

Single item selection on a smartphone
Single item selection on a smartphone

Select a Single Item (Desktop/Tablet)

Clicking the value help icon opens the Select: [Object]  screen (for example, Select: Company). The icon tab bar and the Selected Items / Excluded Items row are hidden. As soon as an item is selected, the value help dialog closes automatically.

Single item selection on a desktop/tablet device
Single item selection on a desktop/tablet device

Select a Single Range (Smartphone)

Tapping the value help icon opens the Define Condition tab.

Single range selection on a smartphone
Single range selection on a smartphone

Select a Single Range (Desktop/Tablet)

Clicking the value help icon opens the Define Condition: [Object] tab (for example, Define Condition: Company).

The icon tab bar and the Selected Items / Excluded Items row are hidden. The Add and Delete icons for adding and deleting ranges are also hidden.

Single range selection on a desktop/tablet device
Single range selection on a desktop/tablet device

Select Multiple Items | Select/Exclude Multiple Ranges (Smartphone)

Tapping the value help icon displays the start dialog.

  • The Select from List tab is used to select multiple items
  • The Define Conditions tab is used to select and exclude ranges.

Both are added as tokens to the Selected Items / Excluded Items row at the bottom of the start dialog.

Start dialog for multi-item and multi-range selection on a smartphone
Start dialog for multi-item and multi-range selection on a smartphone
Multi-range selection on a smartphone
Multi-range selection on a smartphone
Multi-item selection on a smartphone
Multi-item selection on a smartphone
Advanced search on a smartphone
Advanced search on a smartphone

Select Multiple Items | Select/Exclude Multiple Ranges (Desktop/Tablet)

Clicking the value help icon displays the icon tab bar with the Select from List and Define Conditions tabs.

  • The Select from List tab is used to select multiple items
  • The Define Conditions tab is used to select and exclude ranges.

Both are added as tokens to the Selected Items / Excluded Items row at the bottom of the screen.

Multi-item and multi-range selection on a desktop/tablet device
Multi-item and multi-range selection on a desktop/tablet device
Multi-item and multi-range selection on a desktop/tablet device
Multi-item and multi-range selection on a desktop/tablet device

Select/Exclude Multiple Ranges (Smartphone)

Tapping the value help icon opens the start dialog with the Define Conditions tab.

The selected values are added as tokens to the Selected Items / Excluded Items row at the bottom of the start dialog.

Start dialog for multi-range selection on a smartphone
Start dialog for multi-range selection on a smartphone
Multi-range selection on a smartphone
Multi-range selection on a smartphone

Select/Exclude Multiple Ranges (Desktop/Tablet)

Clicking the value help icon opens the Define Conditions: [Object] tab (for example, Define Conditions: Company). The icon tab bar is hidden and the Selected Items / Excluded Items row is displayed.

Multi-range selection on a desktop/tablet device
Multi-range selection on a desktop/tablet device

Selected Items / Excluded Items

  • Each item that is selected from the result list on the Select from List tab is displayed as a token in the Selected Items row.
  • Each range that is selected or excluded on the Define Conditions tab is displayed as a token in the Selected Items / Excluded Items row.

Copying and Pasting Multiple Values

The Include and Exclude areas on the Define Conditions tab allow the user to enter multiple values at once (copied from the clipboard) .

In both areas, users can paste more than one value into the value input field. In this case, the condition row repeats with the previously selected condition and shows one value per row.

If there are more than 10 rows of conditions in either the Include or Exclude area, pagination is added to top of the respective area. A token appears next to each pasted value on the Selected Items / Excluded Items row at the bottom of the value help dialog.

Copying and pasting multiple values
Copying and pasting multiple values
Copying and pasting multiple values
Copying and pasting multiple values

Guidelines

Dialog Title

The dialog title differs depending on the device and whether multiple or single selection is used.

For smartphones:

  • Starting dialog: [Object] (for example, Company)
  • Select from list dialog: Select from List
  • Advanced search dialog: Advanced Search
  • Single range selection: Define Condition
  • Multiple range selection: Define Conditions

For tablet and desktop devices:

  • Multiple items combined with selection of multiple ranges: [Object] (for example, Company)
  • Single item selection: Select: [Object] (for example, Select: Company)
  • Single range selection: Define Condition: [Object] (for example, Define Condition: Company)
  • Multiple range selection: Define Conditions: [Object] (for example, Define Conditions: Company)

Advanced Search

If necessary, also provide value help for fields offered in the advanced search. However, do not provide the full value help dialog for the ID and description fields of the business object that is being selected. For these two fields, make sure that the value help icon opens only the Define Conditions screen (range selection).

For example, in a value help dialog for selecting the customer, do not offer full value help for the Customer ID and Customer Name fields. Instead, try to use the value help in combination with a helpful suggestion.

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)

Intro

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

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.

Columns tab in the P13n dialog
Columns tab in the P13n dialog

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

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

P13n dialog – Sort tab
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

P13n Dialog

Intro

The p13n dialog control provides a dialog for tables that allows the user to personalize one or more of the following attributes:

  • Columns (visibility and order of columns)
  • Sort (sorting of table values)
  • Filter (filtering of table values)
  • Group (grouping for specific attributes)

These tabs can be shown in any combination, as the use case requires.

The P13n dialog is intended for complex tables with a large number of columns and the need for complex queries for sorting, grouping, and filtering.
For simple tables, see view settings dialog and table personalization dialog.

The P13n dialog can be triggered in the table toolbar using the corresponding buttons in the top right-hand corner of the table.

The dialog is shown centered, either as a dialog (on desktop and tablet devices) or as a full-screen dialog (on mobile devices).

Dialog buttons within the table toolbar
Dialog buttons within the table toolbar

Usage

Use the P13n dialog if:

  • The user is able to personalize more than 20 or so columns.
  • You need several functions for sorting, grouping, and so on.
  • You are using the analytical table.
  • Complex queries have to be built for the relevant table.

Do not use the P13n dialog if:

  • The user is able to personalize fewer than about 20 columns.
  • You only need a simple column show/hide feature.

Responsiveness

The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), the dialog is shown as a dialog. For size S (smartphones), the P13n dialog is displayed as a full-screen dialog.

Size S – Columns
Size S – Columns
Size M
Size M
Size L
Size L

Components

The P13n dialog consists of four different tabs that can be used separately or combined, as required by the use case:

  • Sort
  • Filter
  • Group
  • Columns

App developers can add more tabs manually.

Behavior and Interaction

Columns

The first tab is the Columns tab. It allows the user to change the table columns that are shown and the order in which they are displayed.

The list contains all of the table’s possible columns in the form of list items with checkboxes. The checkboxes of the currently displayed columns are selected.

Another button next to the search field in the table toolbar allows the user to toggle between showing all columns and only those that are currently selected in the list.

Show/Hide

To show or hide a column, select or deselect the appropriate checkbox.

Reorder

To change the order of the columns, simply mark one list item and use the buttons on the right-hand side of the table toolbar to move them up or down. The order of the columns from top to bottom corresponds to the order on the table from left to right.

Search

If the table has numerous columns, the user can use the search field in the table toolbar to find a specific column more quickly. As soon as the user enters the first letter, the resulting columns are displayed instantly.

Column settings in the P13n dialog
Column settings in the P13n dialog

Sort

The second tab is the Sort tab, which allows the user to sort the table content according to the chosen attributes, and also in either ascending or descending order.

The sort criterion consists of two input fields. In the first field, the user can choose a column by which the table is to be sorted. In the second field, the user chooses the sort order (ascending or descending).

For more complex sorting needs, the user can add the required number of criteria by clicking the plus “ ” sign at the end of the line.

The order of the criteria is exactly the same as the order in which sorting is applied to the table.

Sort settings in the P13n dialog
Sort settings in the P13n dialog
Information
Using the sort feature on column headers replaces ALL sort options in the dialog!

Filter

The third tab is the Filter tab, which allows the user to filter the table information according to specific criteria.

The filter criteria can be included or excluded in the relevant section of the filter.

Column

In the first input field, the user selects the column to be filtered. Any of the columns can be selected; even those that are not currently visible.

Option

The second field offers an operator for specifying the filter in more detail. The operators that are available depends on the data type of the selected column.

Filter tab in the P13n dialog
Filter tab in the P13n dialog

String (Text)

  • between
  • contains
  • equal to
  • begins with
  • ends with
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Number

  • between
  • equal to
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Date

  • between
  • equal to
  • after
  • on or after
  • before
  • before or on

Boolean (true / false)

  • equal to

The only available operator for excluding values from the filter results is equal to.

Value

The last field contains the value by which the selected column is filtered. The kind of input field that is provided depends on the data type of the selected column.

Two or even more fields can be provided as required by the use case.

For more complex cases, the user can add filters by clicking the plus “ ” button or remove them by clicking the Remove button at the end of each filter item.

Information
If there is a filter bar, use its filter functionality and deactivate the filter feature of the P13n dialog.

Group

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

In the first selection field, all columns are provided for selection. The user can select a checkbox on the right of the column selection field if the selected field is to be displayed as a column anyway.

For more complex grouping scenarios, the user can add more grouping options by clicking the plus “ ” button on the right-hand side of each grouping line. This option only works with the analytical table.

The grouped table shows the selected field as the group header, which can be expanded or collapsed.

Under the group headers, all subgroup headers and all applicable table entries are displayed.

Group tab in the P13n dialog
Group tab in the P13n dialog
Information
To group by a specific column, that particular column must be marked as visible on the Columns tab!

Guidelines

For opening the dialog from a table toolbar, use different buttons for each function (sort, filter, group, column settings). With each button, open the P13n dialog with just the corresponding tab. Do not display the other tabs.

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

Warning
This guideline was written for release 1.52 and is no longer updated. For the latest design guidelines, see the corresponding table articles (Responsive TableGrid TableAnalytical TableTree Table).

Background:
As of guideline release 1.54, the SAP Fiori Design Guidelines contain only general guidelines for all implementations. These guidelines also apply for implementations using smart controls. You can still use the smart table, but the exact features will no longer be updated in the design guidelines.

Intro

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 generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: demandPopin, 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 can 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

Aggregation of Different Currencies

If used with the analytical table, the smart table also allows you to display totals for amount columns with different currencies.

In this case, a Show Details link is displayed instead of the total. Clicking the link opens a popover showing the subtotals per currency.

Exception: If a group contains only one currency, the total is shown directly.

Totals for a column which contains amounts in different currencies
Totals for a column which contains amounts in different currencies

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

The table toolbar can contain a button for exporting the table data to a spreadsheet (sap.ui.comp.smarttable.SmartTable, Property:useExportToExcel). The spreadsheet file can be created using back-end functionality (if available) or in the front-end (sap.ui.comp.smarttable.ExportType):

  • With the back-end export, the following columns are exported: currently visible columns, “technical columns” that are in the data model but not visible to the user, and usually some (but not all) of the columns that are currently hidden. In the spreadsheet file, neither the columns nor the rows are in the same order as in the exporting app. The exported file might also show different column header texts.
    When the user triggers the export, the corresponding file is created in the background and offered for download automatically. The export process cannot be canceled. This option is only available if the back-end export is supported in the corresponding back-end system.
  • With the front-end export (default and recommended), only visible columns are exported. In the exported file, columns are in the same order and have the same header texts as in the exporting app. During the export, the system displays a progress dialog that blocks the UI. The export can be canceled at any time. As soon as the file has been created, it is offered for download automatically. The front-end export is always available.

In both cases, the export works only with simple text-only cell content. Non-text elements, such as icons, images, micro charts, or controls like checkboxes and buttons are not supported. Formatters are not taken into account (for example, for numbers, amounts, dates, and times) .

Warning
With both methods, the file size is limited by the available browser memory. Exporting large tables can therefore lead to memory overflows and browser crashes.

For the front-end export, the recommended maximum table size for using the built-in export functionality is 1 million table cells for desktop browsers or 100,000 table cells on tablets and phones. The limitation for the back-end export is even worse: even on a desktop device, the recommended maximum table size is only around 100,000 table cells.

For larger tables, consider using custom-built, specialized export solutions instead.

'Export to Spreadsheet' button
'Export to Spreadsheet' button
Exporting to Spreadsheet
Exporting to Spreadsheet

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

Use button styles only to help the user and not for decoration. For instance, emphasize the most important action. Use only one emphasized button, and never mix emphasized and semantic buttons.

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

The following default texts are provided automatically:

  • If the smart table is used standalone (without an attached smart filter bar) and it is initially empty (not yet bound), the default text is:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the table with data.
  • If the smart table is used with a smart filter bar attached, and it is initially empty (not yet bound), the default text is:
    No filters set. To start, enter your search and filter settings and run the search.
  • If a smart table is bound but there is no data to display from the binding, the default text is:
    No items found. Check the search and filter settings.
    Overwrite this whenever this text is either not precise enough (for example, only search is offered) or misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).

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)

Highlight Items

If the smart table is used with the responsive table, you can show the status of an item by displaying a highlight indicator in front of the item (property: highlight). 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
Highlighted items
Highlighted items

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 sales order ID
Responsive table grouped by sales order ID

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

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 tableform 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. By contrast, the analytical table supports only a very limited set of controls.
  • The focus is 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 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 expect the table to contain more than around 1,000 rows. Try using the analytical table or grid table instead; they are easier to handle, perform better, and are 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 be more appropriate because each cell contains only one data point. By contrast, the responsive table offers greater flexibility within line items, including the ability to add more data points per cell and 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 child nodes. 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 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
Do not use a responsive table as a form
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 responsive table is optimized for viewing one line item at a time with no scrolling 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 for the corresponding cell is provided as a label/value pair. The label is defined by the column header, and the value is taken from the corresponding cell. Labels can be displayed next to the value or above the value.

Within the pop-in area, the label/value pairs can be displayed in the following ways (sap.m.Table, property: PopinLayout):

  • Block: Label/value pairs are listed one below the other.
  • GridSmall: Label/value pairs are displayed next to each other in equally spaced grid cells. An additional column is shown for each 13 rem of available width (208 px with default browser settings). If the number of grid cells exceeds the available width, the grid cells wrap. On S size, this layout transforms automatically to a block layout.
  • GridLarge: The display logic is the same as for GridSmall,, but grid columns come with a larger minimum width (26 rem instead of 13 rem).

In all layouts, you can show the labels next to or above (recommended) the corresponding data.

The responsive table uses all the available space, and does not provide any padding. If there is space around the table, it comes from the spacing defined for the surrounding layout container.

Information
The GridSmall and GridLarge layouts are not available in all browsers. If the chosen layout is not available, it is automatically changed to Block layout.
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)

The responsive behavior is optional. If it is not used, the responsive table just minimizes all visible columns until they are no longer readable.

There are two ways to configure responsiveness: auto pop-in mode and manual pop-in mode (sap.m.Table, property: autoPopinMode).

The auto pop-in mode ensures responsiveness automatically and is sufficient in most cases. You can still influence the behavior per column, but only to a limited extent.

The manual mode is more flexible, but needs are more configuration. This configuration becomes more cumbersome when table columns can be shown/hidden or re-ordered. On the other hand, only the manual mode allows you to:

  • Let more than one column stay in the tabular layout
  • Move more than one column into the pop-in area at once

In both modes, the responsive table ensures that at least one column always remains in the table layout.

Auto Pop-In Mode

The auto pop-in mode handles responsiveness automatically. You can optimize this to a certain extent by adapting the behavior per column.

Columns have a minimum width. As soon as the width of all the visible columns exceeds the table width, the right-most column moves to the pop-in. The default minimum width per column is 8 rem. You can change this value for each column (sap.m.Column, property: autoPopinWidth).

To further influence the behavior, you can assign columns a priority. Low-priority columns move to the pop-in first (right-most low priority column first), medium-priority columns next, and high-priority columns last. The default priority is “none”, which is handled like the “medium” priority (sap.m.Column, property: importance).

Instead of moving columns to the pop-in area, you can also hide columns of one or more priority levels (property: hiddenInPopin).

In auto pop-in mode, all other pop-in-related column settings are ignored.

Manual Pop-In Mode

The manual pop-in mode allows more flexibility but also requires more effort if you want it to work in a meaningful way. You also need to invest additional effort if table columns can be shown/hidden or re-ordered.

You need to configure each column manually. Depending on the width of the table (in pixels), the column needs to know which of the following responses is required:

  • Stay in the table layout (in auto pop-in mode, only one column stays in the table layout).
  • Move to the pop-in (sap.m.Column, with the properties: demandPopin, minScreenWidth, popinHAlign, popinDisplay).
  • Hide

By default, the table width is assumed to be the screen width. If the table does not use the full width of the screen, app developers must configure the table accordingly (sap.m.Table, property: contextualWidth).

Because you configure the pop-in response for each column individually, you can also handle more than one column at a given breakpoint. This allows you to move several columns to the pop-in area at once, which isn’t possible in auto pop-in mode

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

Example for Block Layout

A typical responsive table.

A typical responsive table
A typical responsive table

Hide the information column for a width smaller than 570 px.

Hiding the information column
Hiding the information column

Move the column “vendor” to the pop-in area for a 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 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 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 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

Example for GridLarge Layout

A more complex responsive table.

A more complex responsive table (full screen without pop-in)
A more complex responsive table (full screen without pop-in)

In this example, the Average Occupancy Rate and Available In columns move to the pop-in area if the screen width is less than 1900 pixels.

GridLarge layout - 'Average Occupancy Rate' and 'Available In' columns move to the pop-in area
GridLarge layout - 'Average Occupancy Rate' and 'Available In' columns move to the pop-in area

If the width is less than 1500 pixels, the Average Stay column moves to the pop-in area.

GridLarge layout - 'Average Stay' column moves to the pop-in area
GridLarge layout - 'Average Stay' column moves to the pop-in area

If the width is less than 1100 pixels, the Description column moves to the pop-in area. Since all four columns in the pop-in area do not fit into one row, the pop-in wraps.

GridLarge layout - 'Description' column moves to the pop-in area
GridLarge layout - 'Description' column moves to the pop-in area

If the width is reduced even further, the Details column moves to the pop-in area. On this narrow screen, only one column fits into one pop-in row, so it looks exactly like the block layout.

GridLarge layout - 'Details' column moves to the pop-in area
GridLarge layout - 'Details' column moves to the pop-in area

Layout

The optional title bar consists of the title of the responsive table, an item counter, variant management, and the toolbar.

The filter info bar appears when the responsive table is filtered, and 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 contains the title of the responsive table, an item counter, 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 AddEdit, 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 within 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, see object display components.
You can use the table footer to display additional static information relating to the table content.
The More button loads more items to the front end if not all items have yet been loaded.
Components of the responsive table
Components of the responsive table

Behavior and Interaction

The responsive table is quite flexible with regard to its content.

Table Level

Scroll

The height of the table is defined by the number 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 triggered by scrolling (preferred), or by clicking the More button.

Same table, different number of items
Same table, different number of items

When the user scrolls, the title bar, column headers, and filter info bar can stick to the top of the surrounding layout container (sap.m.Table, property: sticky).

Information
The “sticky” feature comes with some limitations:

  • It is not available on all browsers. In non-supporting browsers, the corresponding areas (title bar, column headers, filter info bar) are not fixed on top of the surrounding layout container while scrolling.
  • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the table is placed within the object page.
  • If focus is set to a fixed column header, the table is automatically scrolled to top.

Sticky table title and sticky column header
Sticky table title and sticky column header

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.
  • If the corresponding column can contain blank cells. Otherwise, it is cumbersome to differentiate between blank values and merged values.
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 modes (sap.m.Table/ sap.m.ListBase, property: mode):

  • None: Items cannot be selected (sap.m.ListMode.None).
    Beware: Line items can still use the sap.m.ListType “navigation”, which allows click handling on specific line items. Only use this option if the click triggers navigation to a corresponding line item details page.
  • Single selection master: One item in the responsive table can be selected. Items are selected by clicking the whole row. The single select master mode has no obvious visual cues, such as checkboxes or radio buttons. It only provides a light blue background for the selected state. Because of this, it can barely be differentiated from tables without selection (mode: None). Single select master is the preferred mode for single selection (sap.m.ListMode.SingleSelectMaster).
  • Single selection left: One item in the responsive table can be selected. For this, the responsive table provides radio buttons on the left side of each line item. Only use this mode if row clicks are being used for something else, such as navigation. (sap.m.ListMode.SingleSelectLeft).
  • Multiple selection: Users can select one or more items using the checkboxes on the left side of each line item. The Shift key can be used to select a range. Users can (de)select all items using the Select All checkbox to the left of the column header. Select All should (de)select all items that the user can reach by scrolling.  (sap.m.ListMode.MultiSelect).
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.
SIngle selection left, with radio buttons. Use only if row clicks are used for something else.
Multiple selection
Multiple selection

Group

For grouping items, a group header is displayed (sap.m.GroupHeaderListItem). 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 items already loaded 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 in growing mode. 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 'delete' mode
Responsive table in 'delete' mode

Highlight an Item

To highlight an item, use the “highlight” indicator (sap.m.ColumnListItem, properties: highlight).

Highlighted item
Highlighted item

Navigate

To allow navigation from a line item, use an item with the type “navigation” (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This creates an indicator at the end of the line (“>”) and the entire line item becomes clickable. If the user clicks on the line, 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.

By contrast, clicking an interactive control within a line item does not trigger the navigation event. Instead, the corresponding control handles the click event.

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

Indicate Navigated Item

When multi-selection is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case only (multi-selection table with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.ColumnListItem, property: navigated).

Navigated item
Navigated item

Edit Line Items

To allow editing for a line item, 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, for example, 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

Drag and Drop

One or several items can be repositioned within a table or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop
Whole item as drop target
Whole item as drop target

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column). Context menus can be implemented for a specific table or row.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or SHIFT+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Responsive table with a context menu
Responsive table with a context menu

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

Alongside textual elements, you can also add any control to a table cell, such as input fields, microcharts, buttons, and so on.

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.

With the View Settings dialog, users can sort, filter, and group by each of these data points.

Several controls per cell
Several controls per cell

You can also have different controls in different rows in the same column. This could be the case if one item is locked, but another item is in edit mode, for example.

Different controls per column
Different controls per column

Guidelines

Responsiveness

In most cases, the auto pop-in mode is sufficient. If you need to optimize further, first try to adapt the columns to influence the automatic behavior (sap.m.Column, properties: autoPopinWidth, importance). For example, set the priority for the two or three most important columns to “High” (identifying column, key attribute).

While the pop-in layouts GridLarge and GridSmall make better use of the available width, they also only look good with content that is specifically designed for these pop-in layouts. If you have text-only tables with only one value per column, use the Block layout (sap.m.Table, property: popinLayout).

Place the column header labels in the pop-in area above the corresponding values (sap.m.Column, property: popinDisplay, value: Block). This avoids alignment issues with different content. Be aware that the labels get top-aligned with the adjacent content.
Only place the label next to the corresponding value under the following conditions (sap.m.Column, property: popinDisplay, value: Inline):

  • The values are text-only (no input fields, icons, images, micro charts, and so on)
  • The available space is at least the double the width of size S.

This avoids truncation or “over-wrapping” of the labels and content.

If a column does not have a column header text (for example, if it always contains the same button with its own label), do not show the header text as a label in the pop-in area either (sap.m.Column, property: popinDisplay, value: withoutHeader). If you forget this setting, you will see an empty space followed by a colon (“:”).

Information
The GridSmall and GridLarge layouts are not available in all browsers. If the chosen layout is not available, it is automatically changed to Block layout.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the responsive table. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning
The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

  • The number of rows in the table
  • The number of displayed columns
  • The complexity of the cell content (for example, simple text vs. complex charts)
  • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
  • The browser being used

Table Title

Implement the table title by using a title control in a toolbar.

Use a table title only if the title of the table is not indicated in the surrounding area. Do not use a table title if it simply repeats text that is already above the table. For example:

  • A pricing conditions table is the only control on a tab labeled Pricing Conditions.
  • A section or subsection on an object page contains only one table.

Use a table title if you need the item count, table toolbar, or variant management. To avoid repeating text, feel free to use generic text as a table title, such as Items.
Exception: If the surrounding area contains the table title, and both the item count and toolbar can be added to the surrounding area, no additional table title is needed.
Example: An object page (sub-)section contains only one table. In this case, add the item count and the table toolbar to the (sub-)section header.

Developer Hint
Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table.

If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

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)

The item count in the table title includes all the visible items that a user can reach by scrolling. Group headers are not included.

Remove the item count in the table title if there are zero items. Do not use an item count together with “growing mode”.

If possible, keep the title bar sticky (sap.m.Table, property: sticky).

Table title with item count
Table title with item count

Selection

If the click area for the row is being used for another purpose (such as navigation), it cannot be used for selecting the row. In this case, use the “single select left” selection mode, which offers a radio button as an additional click area for each row. To avoid confusion, make sure that the first data column does not contain radio buttons in default delivery.

In all other single selection cases, use the selection mode “single select master”.

For all single selection modes, make sure that one item is initially selected. Otherwise, the user cannot return to the initial state. A selected item can only be deselected by selecting another item.

In multiple selection mode, do not show checkboxes in the first data column in the default delivery to avoid confusion. Offer the Select All checkbox for (de)selecting all items the user can reach by scrolling.

Don't
Single selection left - Do not show radio buttons in the first column in the default delivery
Single selection left - Do not show radio buttons in the first column in the default delivery
Don't
Multiple selection - Do not show checkboxes in the first column in the default delivery
Multiple selection - Do not show checkboxes in the first column in the default delivery
Do
Use the selection mode
Use the selection mode "single select left" if clicking the row is used for something else (such as navigation)
Do
Use the selection mode
Use the selection mode "single select master" in all other single-selection cases
Developer Hint
Select All is only applied to items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded, such as items added via lazy loading with growingScrollToLoad. This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

To process all items, listen to the selectionChange event and to its selectAll flag. This indicates whether the Select All checkbox was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

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 three to five columns if the responsive table is shown within the flexible column layout. Use about eight columns if using the full screen width, depending on the content.

If the responsive table does not fit into the width provided:

  • 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 into the width provided, 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, no column header label is needed as long as at least one column still has a column header label.

Use controls that wrap and support wrapping with hyphenation, such as text (with wrapping and hyphenation enabled). Do not use controls that truncate.

Keep column headers sticky.

Do
Wrap column headers
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 (rarely used)
Accepted: Link as column header text (rarely used)
Accepted if responsiveness is taken into account: Text plus search field
Accepted if responsiveness is taken into account: Text plus search field

If a column cell contains several fields, use an umbrella term in the column header (such as Address for fields like Street, ZIP Code, and City).

For text and ID fields, use a generic label (for example, Employee for Name and ID).

If none of these are possible, separate the labels with “/” (for example, Name / Status).

For boolean values, such as checkboxes, find a descriptive text for the column header.

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.

Exception: Secondary information in a column always follows the alignment of the main information.

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

Left-align status information.

Left-align status information
Left-align status information

Center-align icons.

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
Use top-alignment where possible
Use top-alignment where possible
Don't
Do not use top alignment if it doesn't make sense
Do not use top alignment if it doesn't 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 table 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
If displayed as a link, use the whole text as the link
If displayed as a link, use the whole text as the link

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
Is displayed as a link, use only the first line as the link
Is displayed as a link, use only the first line as the link

If there is more than one key identifier (for example, First Name and Last Name), display these columns first and show the values in bold text.

Several key identifiers
Several key identifiers

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 and support hyphenation.

For example, use text.

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 to offer edit mode, change your text controls (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 – Inline
Interactive controls – Inline

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

Flag and Favorite

Place the flag or favorite marker in the first column (in the default delivery). To change the settings, users need to drill down into the object itself.

Item marked as a favorite
Item marked as a favorite

Empty Tables

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

Examples:

  • If a table is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the table with data.
  • If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    To start, set the relevant filters.
  • If a table is used together with a filter bar and the filter does not return results, use the following text:
    No data found. Try adjusting the filter settings.

Adapt the texts above if:

  • The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of filter settings).

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 contains 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. To do this, use an object status control with the error state (sap.m.ObjectStatus, property: state, value: sap.ui.core.ValueState.Error).

In addition, highlight the row accordingly (sap.m.ListItemBase, property: highlight).

A modified item with an error
A modified item with an error

To show that an item is locked, use a transparent button with the corresponding icon and the text Locked by [Name] at the bottom of the identifying column. The user can click 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 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, you can show a highlight indicator next to the item. The highlight indicator can indicate:

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It doesn’t tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted items using status colors
Highlighted items using status colors
Highlighted items using industry-specific (indication) colors
Highlighted items using industry-specific (indication) colors

Numbers and Units

If the following conditions all apply, show the unit of measurement in the column header:

  • The unit of measurement is the same for all rows
  • A single cell contains only one amount with the unit of measurement
  • The column header does not scroll away

In all other cases, show the unit of measurement together with the corresponding amount within the row.

Show the unit of measurement in the same column as the corresponding amount.

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 table width is narrow, 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)

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, it is not accessible, since there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.

Use drag and drop only in addition to existing visible UI elements
Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within the table, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop targets in between items
Drop targets in between items

Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on values in a column, the dropped item needs to take on the value of the target group for the corresponding column. If this is not wanted, do not allow users to rearrange items in grouped tables.

Example:
A table is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Don't
Do not combine rearranging items with grouping, unless you know exactly what you're doing.
Do not combine rearranging items with grouping, unless you know exactly what you're doing.

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

The context menu can be triggered for the whole table or per row.

Actions

To trigger actions on multiple items, use a multiselection table (sap.m.Table, property: mode, value: sap.m.ListMode.MultiSelect), and offer the corresponding actions on the table toolbar. Keep the table toolbar sticky (sap.m.Table, property: sticky).

Do not offer actions for 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. One example would be an Add to Cart button in a shopping application. 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 a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.
Inline actions
Inline actions

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Give users the option to apply the action anyway or to cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element – States.

If the action was applied, and if the items are still available, keep them selected.

Message for an action that applies to a part of a selection
Message for an action that applies to a part of a selection
Place actions near to the objects to which they belong
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

For adding items, place an Add or Create text button on the table toolbar.

  • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
  • Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the table, with a visual highlight at the beginning of the row.

There are three options for adding an item after the Add button is pressed. In order of priority (most recommended first), these are:

  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 just a few columns and no option to hide columns.
  2. Open a dialog for larger tables with up to 8 editable 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 that cannot be handled by a dialog (for example, tables with more than 8 columns). When the user presses Save in the footer toolbar of the create page, navigate back to the table.

A new item can have three different states:

  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 to keep the item visible.
  3. As soon as the responsive table is sorted, filtered, or grouped again, the action is also applied to the new item. It then also loses the visual highlight.

In the context of the draft handling new items are not saved on table level, but rather with the entire draft.

For more details, see the guidelines for managing objects (including subarticles).

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 highlighted, still the first item
Saved new item, still highlighted, still the 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.

For details, see mass editing.

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)

Sort

For the default sort settings, sort by the column that identifies the row, which is usually the first column in default delivery. From this column, use the primary data point.

If you offer sorting, offer it for each data point. In other words, allow sorting by both the primary and secondary information in a column. Allow sorting in both directions, ascending and descending. The descending sort order must always be the exact reverse of the ascending sort order.

For each data point, provide a meaningful sort order. For example:

  • Sort text alphabetically
  • Sort numbers by their value
  • Sort status information by the severity of the status:
    • Ascending: Sort status information from positive to negative, with neutral last.
    • Descending: Sort status information from negative to positive, with neutral first.
Object status sorted ascending, with neutral status last
Object status sorted ascending, with neutral status last
Object status sorted descending, with neutral status first
Object status sorted descending, with neutral status first
    • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
    • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.
Object status sorted ascending and alphabetically, from positive to negative with neutral last
Object status sorted ascending and alphabetically, from positive to negative with neutral last
Object status sorted descending and alphabetically, from negative to positive with neutral first
Object status sorted descending and alphabetically, from negative to positive with neutral first

Filter

To display the current filter state, use the info bar below the table title. Clicking 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.

Keep the info bar sticky (sap.m.Table, property: sticky).

Developer Hint
To display the current filter settings on the info bar, consider using the list formatter (sap.ui.core.format.ListFormat).
Filtered table
Filtered table

Group

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

If there is no grouping value, show the following text:
[Label of the grouped column]: (Not Available)

This is the case if you have a group of items that don’t have a value for the grouped column.

Grouped table, with missing grouping value
Grouped table, with missing grouping value

Persist the view settings. When a user reopens the app, show the responsive 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.

If all columns are hidden, the table shows a corresponding “no data” text.

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.

Tables in Object Pages

To show a table in the object page content area, use the responsive table.

A responsive table with up to 20 expected items can be displayed right away, without lazy loading.
If you expect the table to have more than 20 items, use one of the following 3 options:

  1. Lazy loading (More button): Use this option if you expect to have up to 100 items.
  2. Tab navigation: If you expect to have more than 50 to 100 items, but less than 400, use the object page with tab navigation instead of anchor navigation. Put the table on a dedicated tab.
  3. Navigation to a list report: If you expect the table to have more than 400 items, or if the tab approach is unsuitable, restrict the number of items in the table itself to a reasonable amount. To provide the user with a way to work with the entire table, offer navigation to a separate list report containing the full table.

For all of the three options mentioned above, we recommend providing a search, and if feasible, sort and filter capabilities for the table in the object page. Grouping should be avoided.

For more information on the use of tables within the object page, see the Tables section of the Object Page article.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting table data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button
'Export to Spreadsheet' menu button

Paste

To paste data from the clipboard to the table, the browser functionality for paste can be used (CTRL + V or browser context menu).

  • If the focus is on row level, the app has to take the data from the clipboard and add it to the corresponding controls within the table.
  • If the focus is on an editable control within the table, the control gets the data automatically.

Pasting via context menu does not work if a custom context menu is used.

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 for a large 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: inset 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.
  • The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). 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

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.

Actions and Layout

Actions can be used as follows:

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

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

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

Responsiveness

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

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

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

Responsive toolbar – Size L
Responsive toolbar – Size L
Responsive toolbar – Size S
Responsive toolbar – Size S

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. The  “” (overflow) button is a toggle button and can be used to switch the overflow menu on and off.

The user clicks the overflow button to open a popover. In this action sheet, all icon buttons are labeled with text. Overflow is supported for the following controls:

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.

The sap.m.ToolbarSeparator can also go into the overflow. The separator then changes from a vertical line into a horizontal line. If the control happens to be the first or the last item of the overflow area, the separator isn’t displayed.

Prioritization

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

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

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

Grouping

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

Table toolbar on desktop without overflow
Table toolbar on 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

Header and Footer Toolbars

Use the following button styles for the different action types in the header and footer toolbars:

  • Primary action: Use the emphasized button style.
  • Secondary action: Use the ghost button style. Note that the ghost button has a transparent background.
  • Semantic action: Use the semantic buttons for positive and negative actions. Use the “accept” style for positive actions, and the “reject” one for negative actions. Semantic actions must always be text buttons.
  • Negative path action: Use the transparent button style.

Do not use any other style types.

Content Toolbars

Use the following button styles for the different action types in content toolbars (for example, in tables, forms, or charts):

  • Primary action: Use the emphasized button style. Usually, the primary action is positioned in the header or footer toolbar. Note that there can only be one primary action per page. If a page already has a primary action, but you also need to highlight the most important action in a content toolbar, use the ghost style for this one button in the content toolbar.
  • Secondary action: Use the transparent button style.

The different button styles are designed to give appropriate feedback to users. Do not use them for decoration purposes.

Button with different styles
Button with different styles

Styles and Toolbars

Apply the following menu button styles for the different toolbars:

  • Header and footer toolbars: Use the ghost style.
  • Content toolbars: Use the transparent button style.

Do not use any other style types.

Emphasized and Semantic Buttons

  • Use a maximum of 1 emphasized button per toolbar.
  • Never mix emphasized and semantic buttons.
  • Ideally, there should be only one emphasized action per page. There can be valid exceptions, but we generally recommend using only one emphasized button.
  • For more information, see Buttons.

Enumeration

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

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

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

Types

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

  • Header toolbar: Contains global actions that are important for the whole page
  • Footer toolbar: Contains only closing and finalizing actions
  • Table toolbar: Toolbar that is positioned above a table and contains table-specific actions
  • Chart toolbar: Toolbar that is positioned above a chart and contains chart-specific actions
  • Infobar: Toolbar that indicates what filters have been set, and how many items have been selected
  • Tree toolbar: Toolbar that appears above a tree or tree table, and is used for actions that impact the entire tree.

Header toolbar with primary action (emphasized style) and secondary actions (ghost style)
Header toolbar with primary action (emphasized style) and secondary actions (ghost style)

Footer toolbar with standard actions: 'Save' (emphasized) and 'Cancel' (transparent)
Footer toolbar with standard actions: 'Save' (emphasized) and 'Cancel' (transparent)

Table toolbar with search field, text buttons (ghost and transparent style), icon buttons (transparent style), and segmented button
Table toolbar with search field, text buttons (ghost and transparent style), icon buttons (transparent style), and segmented button

Chart toolbar
Chart toolbar

Inactive infobar (not clickable)
Inactive infobar (not clickable)
Active infobar (clickable)
Active infobar (clickable)

Tree toolbar
Tree toolbar

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.
  • Place semantic buttons side by side (for example, Accept and Reject).
  • 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.
  • Do not use icon buttons for app-specific actions (neither icon-only buttons, nor icon+text buttons).
  • 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

Status Indicator

The status indicator uses a filled shape to visualize a single value. Unlike the progress indicator or the radial micro chart, the indicator provides the user with a meaningful association through its use of icons. You can embed the status indicator in other controls.

Selection of status indicators
Selection of status indicators

Usage

Use the status indicator if:

  • You need to display a single value with an icon that describes its context.
  • You need to display a single value that can be updated in real time without reloading the page.

Do not use the status indicator if:

  • You need to display a single value within a table. Use the progress indicator or radial micro chart instead.
  • You need to show a rating. Use the rating indicator instead.
  • The status indicator does not provide the user with any meaningful information and would be for decoration only.

Responsiveness

The status indicator provides four different sizes: small (size S), medium (size M), large (size L), and extra-large (size XL).

For the small size, the partial fill is replaced by a fully-filled shape that can only indicate the semantic per threshold reached.

Layout

A status indicator can consist of a scalable vector graphics (SVG) shape and additional information, such as a label. The status indicator can be configured as a shape only (default), or as a shape with a fixed label.

Shape Only

By default, the status indicator consists of a single shape. We recommend using this type of status indicator when you need to display a fraction of a value, rather than a specific value.

Status indicator - Shape only
Status indicator - Shape only

Shape with a Fixed Label

This type of status indicator includes not only a shape, but also a label that uses semantic colors defined for the the value thresholds of the status indicator. In addition, you can switch between different alignment options, such as left, right, top, or bottom. We recommended using this type of status indicator when the user needs to see the exact value.

Status indicator - Shape and label
Status indicator - Shape and label

Types

Linear Fill

Most shapes can be filled linearly. You can set the shape to be filled from the left, right, top, or bottom, or define a specific angle for filling.

Status indicator with linear fill
Status indicator with linear fill

Circular Fill

For round shapes, you can use the circular fill.

Status indicator with circular fill
Status indicator with circular fill

Filling Sequence

The sequential fill option is useful when the shape consists of multiple parts. You can fill the parts sequentially one by one, or set your own filling order.

Status indicator with filling sequence
Status indicator with filling sequence

Grouping

You can group several shapes together and decide how the filling should be orchestrated among the shapes in this group.

Status indicator grouping
Status indicator grouping

Thresholds

You can set one or more thresholds for each status indicator and assign a color to each threshold. The color changes when a threshold has been exceeded. Only use thresholds and semantic colors if they are meaningful to the user. Do not use them for decoration.

Status indicator tresholds
Status indicator tresholds

Behavior and Interaction

You can define a click event for the status indicator. If the status indicators are grouped, you can define a click event for each status indicator or for the entire group.

Information
When setting a click event for a non-filled shape, we recommend using a darker background color to emphasize that the shape is clickable and not disabled.

Guidelines

Shape Definition

You can download the predefined shapes or create your own custom shapes. For more information on how to create custom shapes correctly, see the API documentation.

Developer Hint
Only circle, rectangle, and path tags are supported inside the SVG file.

Animation Duration

Shape animation follows the motion design principles, with a maximum duration of 250 ms (small moves).

Examples

Status indicator in micro process flow
Status indicator in micro process flow
Status indicator in custom overview page card
Status indicator in custom overview page card
Status indicator in object page header
Status indicator in object page header
Status indicator in tiles
Status indicator in tiles

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

Rich Text Editor

The rich text editor (RTE) is a complex control for data input and editing. It allows users to format the text and insert different types of elements within the text, such as images and hyperlinks.

The rich text editor uses the third party component TinyMCE. In addition to the native toolbar, you can also use a toolbar built with SAPUI5 controls. This custom toolbar acts as a wrapper around the native toolbar and takes care of synchronizing the state of the internal controls with the current state of the selection in the editor.

Rich text editor
Rich text editor

Usage

Use the rich text editor if:

  • You want to enable users to enter rich text with different styles and colors.
  • You need to provide an instrument for texts that require additional formatting.

Do not use the rich text editor if:

  • You want to let users add simple text that doesn’t require formatting. Use text area instead.

Responsiveness

The rich text editor is intended primarily for use on desktop devices, even though it still displays smoothly on mobile devices. You can also enable the mobile theme of TinyMCE, but we don’t recommend using it as it comes with some limitations explained in the Mobile Theme section.

Overflow Behavior

On smaller screens, the custom toolbar utilizes the overflow behavior of the standard SAP Fiori toolbar.

If the available actions do not all fit into the available space in the toolbar, the extra actions disappear from the visible part of the toolbar from right to left, and an overflow menu button appears on the right of the toolbar. Clicking the overflow button reveals the hidden options.

Each action has a priority, which determines whether and when the action moves into the overflow menu. You can 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.
  • Low: Actions with the priority “Low” overflow first. Assign this status to actions the user rarely needs.
  • High: Actions with priority “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.
Size S
Size S
Size M
Size M
Size L
Size L

Mobile Theme

From version 4.7, TinyMCE provides native mobile support with the mobile theme. If your use case requires it and you have enabled the mobile theme, the custom toolbar cannot be used, and the native TinyMCE toolbar and layout are loaded. This is why we don’t recommend using the mobile theme.

Layout

The rich text editor has two main components – the toolbar and the content area.

  • Toolbar: All available actions are displayed in the toolbar. App development teams can add or remove individual action groups, depending on the use case.
  • Content area: The content area is where users create their text. It visualizes all the changes made using the actions in the toolbar.
Schematic visualization of the rich text editor
Schematic visualization of the rich text editor

Toolbar Types

The rich text editor comes with two types of toolbar: the common TinyMCE toolbar and the custom toolbar.

The first image shows the default (native) toolbar, which comes with its own behavior for smaller screens.

Rich text editor - Native TinyMCE toolbar
Rich text editor - Native TinyMCE toolbar

The next image shows the custom toolbar, which includes common SAP Fiori controls and utilizes the overflow toolbar behavior. All common actions provided by the native toolbar are also offered by the custom toolbar.

Rich text editor - Custom SAP Fiori toolbar with overflow
Rich text editor - Custom SAP Fiori toolbar with overflow
Developer Hint
You can decide which toolbar to use. Bear in mind that the type of toolbar is only considered when control is being initialized. It cannot be changed during runtime because of lifecycle incompatibilities between SAPUI5 and the third-party library. You can enable the TinyMCE mobile theme, but once you do so, the native TinyMCE toolbar and layout are always loaded.

Actions in the Custom Toolbar

The custom toolbar includes most of the native TinyMCE actions. The actions are separated into several virtual groups. You can hide each group of actions individually if it is not required by the use case.

Rich text editor - Actions in the custom toolbar
Rich text editor - Actions in the custom toolbar

1) Font Styles: A group of four styles that can be applied to individual symbols (Bold, Italic, Underline and Strikethrough). All of the actions can be combined, which means that a preselected text can be bold, italicized, underlined and crossed out at the same time.

2) Align Text: A group of actions for aligning the text: Align Left, Align Right, Center and Justify. By default the text is left aligned. The selected style is applied to the entire paragraph.

3) Styles: Offers a list of predefined styles, including 6 heading levels and a paragraph. The default style is Paragraph.

4) Font: Changes the font family of the text. All the available fonts are displayed in a select control. 17 font families are supported, including popular fonts like Verdana, Tahoma, Arial, Times New Roman, and Helvetica. The change is applied to individual symbols.

5) Font Size: Changes the size of the text. All available font sizes are displayed in a select control. The minimum size is 8 pt and the maximum size is 36 pt. The change is applied to individual symbols.

6) Text Color: Opens a menu with different options for choosing the color of the text, including a color picker dialog. The default text color is black.

7) Background Color: Opens a menu with different options for choosing the color of the background, including a color picker dialog. The default background color is white.

8) List Type: Part of the structure group. There are two types of list: Bulleted List and Numbered List. This action is applied at paragraph level and turns a normal paragraph into a list. The two list types cannot be applied simultaneously.

9) Text Indent: Part of the structure group. These two actions let users increase or decrease the indentation of the text.

10) Link: A group with two actions: Insert/Edit Link and Remove Link.

11) Insert/Edit image: This option opens a dialog for adding and editing images. Users can also define some of the image properties, such as the width, height, and description.

12) Insert Table: Inserts a simple table within the content area.

13) Clipboard: This action group includes the Cut, Copy, and Paste actions.

14) Custom Action: If the use case requires an action that is not available in the set of common actions, you can attach an external plugin to the custom action. Technically, you can add as many custom actions as you like. However, because custom actions are displayed after the common actions, we recommend keeping the number of custom actions down to a reasonable level.

Developer Hint
The rich text editor is actually an SAPUI5 wrapper around the open source TinyMCE editor. TinyMCE’s functionality can easily be extended using plugins, which can also be attached to the custom toolbar.

The general approach for enabling 3rd-party TinyMCE plugins for the rich text editor is:

  1. Create or find a plugin.js file and place it in convenient place in your application. Alternatively, define the plugin directly in your code.
  2. Load or call the plugin after the TinyMCE core library has loaded. This can be done in the rich text editor’s beforeEditorInit hook.
  3. Add the plugin to the TinyMCE instance.
    • If you’ve defined the plugin directly in your code (synchronous), you can also enable the plugin in the beforeEditorInit hook.
    • If the plugin is in external file and is loaded asynchronously, the plugin should be registered in the instance when the plugin file is downloaded. A convenient place to enable the plugin is the rich text editor’s ready or readyRecurring event.
  4. Optional: If the rich text editor is instantiated with the custom toolbar, be sure to add a custom button to it to make the functionality available.

Important: Third-party plugins are not supported by SAP. We cannot guarantee that there will not be any issues with their enablement.

Behavior and Interaction

General Information

The rich text editor is only available in edit mode of the floorplan it is displayed in. In display mode the content is shown as it is formatted by the user. The user-defined formatting cannot be overwritten.

The toolbar is always visible and the user has access to all the action groups. To start typing, the user has to click inside the content area.

To apply any of the actions from the toolbar, the user has to select the text to be formatted upfront.

Some of the actions can be preselected and applied prior to typing the text. These actions are:

  • Font family, font size and styling (bold, italic, underline)
  • Paragraph alignment
  • Color selection (text color and background color)

Font Styles

The user selects the font style using the respective icon toggle buttons (Bold, Italic, Underline, Strikethrough). The style is applied to a preselected text and remains active until the user clicks the button again or moves the marker to an area where a different style is applied, or no style is applied.

Alignment

The user can change the alignment of the text (Align Left, Align Right, Center, Justify).

By default the text is left-aligned. The selected style is applied to the entire paragraph. To apply any of the styles, the user selects the text and then clicks on the Align Text button  . It is also possible to select the alignment upfront, but in this case only the text written after the selection will have the desired alignment.

Font

The user selects the desired font family from a list of all available font families. The selected font family can be applied to a preselected text, or selected upfront. The default font family is Verdana.

Font Size

The user selects the desired font size from a list of font sizes from 8 pt to 36 pt. The selected font size can be applied to a preselected text, or selected upfront.

List Types

The user can create two types of lists, both of which are triggered by toggle buttons: bulleted lists   and numbered lists  . List formatting is applied at paragraph level. To apply list formatting, the user preselects the relevant paragraphs and selects the relevant list type action.

Text Indent

The text indent defines the amount of empty space in front of a paragraph. The user can increase the indentation  , or decrease it  . Both actions are triggered by standard buttons, and are applied at paragraph level. To change the indentation, the user selects the paragraph (or just positions the cursor within the text) and selects the indent action. The text is moved 30 px left or right, depending on the action chosen.

Color Selection

The user can change the text color and the background color. The chosen colors can be applied to a preselected text or selected upfront.

To choose a color, the user clicks on the color arrow button for the font or background (the right-hand segment of the split button). This opens a popover where users can choose the default color (black for text, white for background), select one of 15 predefined colors, or open a separate color picker dialog.

Within the color picker dialog, the following options are available:

  • Move the circle inside the color field
  • Define RGB values
  • Define HSL values
  • Enter the HEX value
  • Use the horizontal color slider

Users can also define the transparency with the transparency slider.

Clicking OK confirms the selection.

The user can also apply the most recent font or background color without opening the color palette or the dropdown menu. This is done by pressing the left-hand segment of the split button.

Inserting, Editing, and Removing Links

The Insert/Edit Link button opens a dialog for entering the link details. These include the URL, the link text, a title, and the target for the link (same or new browser window) .

It is also possible to attach a link to a preselected text and to edit details for an existing link.

The Remove Link button   is only active when an existing text link has been selected.

Inserting and Editing Images

The Insert/Edit Image button opens a dialog for entering the image URL, a description, and the size.

Beforehand, the user must upload the image to a library that is accessible. In the dialog itself, users can only enter an existing image link. Images cannot be uploaded directly to the server.

To change the alignment of the inserted image, the user selects the image and applies the relevant alignment action. The text around the image is positioned as follows:

  • Right-aligned image: The text is displayed to the left of the image.
  • Left-aligned image: The text is displayed to the right of the image.
  • Centered image: Only the image is displayed in the center of the paragraph.

Users can also edit the URL, description, and size of an existing image by selecting the image and choosing Insert/Edit Image.

Guidelines

Minimum Width

Although the control allows a minimum width of 6 rem (96 px), we recommend setting the width to at least 17.5 rem (280 px). Any less will make the editor practically unusable.

Minimum Height

The minimum height of the control is 12.5 rem (200 px), which ensures that the editor is usable.

Number of Actions in the Toolbar

Only offer actions that are relevant for the use case. If you just need simple text formatting (such as bold, italic, underline, and strikethrough), remove the other groups.

Custom Plugins

Exercise judgement when adding custom plugins to the editor. Only offer a reasonable number of additional options.

Use self-explanatory icons for custom actions. Do not use a text label, or combine a text label with and icon.
As for all icons, offer a tooltip with a text label instead.

Additional Guidelines

The guidelines for the following controls also apply:

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

Calendar

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

When to Use

Use the calendar if:

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

Do not use the calendar if:

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

Components

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

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

Calendar with current date and selected date
Calendar with current date and selected date
Clickable areas of the calendar
Clickable areas of the calendar

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

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

Calendar without calendar weeks and with disabled days
Calendar without calendar weeks and with disabled days

Month and Year View

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

Month view
Month view
Year view
Year view
Year range
Year range

Legend for Highlighted Days

Within the calendar, special days can be highlighted. A legend is used to define the meaning of the highlights.

Calendar with highlighted days and legend
Calendar with highlighted days and legend

Types

The following calendar types are available:

  • Single day selection: The user can select a single day at a time.
  • Single interval selection: The user can select an interval or one entire week.
  • Multiple day selection: The user can select multiple days, which do not have to be next to each other. It’s also possible to select entire week(s) and a date range.
  • Multiple months: Use this calendar type if users need to see more than one month to make their selection. You can offer single day selection or multiple selection (such as multiple days, entire weeks, or date ranges). We recommend showing no more than two or three calendars at the same time.
Single day selection
Single day selection
Single interval selection
Single interval selection
Multiple day selection
Multiple day selection
Multiple month view
Multiple month view

Behavior and Interaction

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

Selecting a Single Date

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

Single day selection
Single day selection

Selecting a Single Interval

The user selects a single interval by clicking the first and last day of the date range, which also selects all the days in between. Alternatively, the user can select two different dates and press SHIFT and ENTER twice.

Single interval selection
Single interval selection

Selecting an Entire Week

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

Selection of an entire week by clicking on the calendar week
Selection of an entire week by clicking on the calendar week

Selecting Multiple Days

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

Selection of multiple days
Selection of multiple days

Changing Months

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

Changing the month using the month view
Changing the month using the month view

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

Changing the month using the arrow
Changing the month using the arrow

Changing Years

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

Changing the year using the year view
Changing the year using the year view

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

Changing the year using the arrow
Changing the year using the arrow

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

Changing the year range in year view
Changing the year range in year view

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

Changing the year range in year view
Changing the year range in year view

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

Changing the year range
Changing the year range

Responsiveness

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

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

Related Topics

Elements and Controls

Implementation

Single Planning Calendar

The single planning calendar is a scheduling control that displays the calendar of a single person or resource over a day, work week, or week. Users can view appointments, create new appointments, and delete appointments.

Single planning calendar
Single planning calendar

Usage

Use the single planning calendar if:

  • You want to enable users to schedule or monitor the calendar of a single person or resource.
  • You want to offer multiple calendar views (day, work week, week).

Do not use the single planning calendar if:

  • You want to compare objects of the same type over a given period (for example, appointments for multiple persons or resources). In this case, use the planning calendar.
  • The main use case is to schedule all-day appointments, and you don’t need to see an hour axis. In this case, use the planning calendar.
  • You need a complex graphical representation or planning application involving activities, resources, hierarchical project structures, relationships, and so on. In this case, use the Gantt chart.

Responsiveness

The single planning calendar is responsive and supports the cozy and compact density modes.

Overflow Behavior

On smaller screens, the custom toolbar utilizes the overflow behavior of the standard SAP Fiori toolbar.

If the available actions do not all fit into the available space on the toolbar, an overflow menu button appears on the right of the toolbar. The rightmost actions move into the overflow menu first.

Single planning calendar - Size L
Single planning calendar - Size L
Single planning calendar - Size M
Single planning calendar - Size M
Single planning calendar - Size S
Single planning calendar - Size S

Components

The single planning calendar consists of the following components:

  1. Header
  2. Toolbar
  3. View switch
  4. Navigation
  5. Date strip
  6. All-day appointment
  7. Timeline
  8. Appointment
  9. Calendar grid
  10. Now marker
Components of the single planning calendar
Components of the single planning calendar
Developer Hint
To prevent waiting time, app developers should load the sap.ui.unified library.

1. Header

The header contains the toolbar and the navigation.

2. Toolbar

The toolbar consists of the calendar title (optional) and the toolbar actions, including a default view switch. You can add other app-specific actions that are relevant for your use case (such as creating an appointment, search, filter, settings, showing the calendar legend, and so on). Always place actions that affect the entire calendar in the toolbar.

3. View switch

The view switch allows the user to switch between different time intervals. The default views are day, work week, week, and month. The app developer can choose which views to include, depending on the use case.

In the month view, all appointments for the respective day have the same width and height. Each grid cell can hold 4 appointments in compact mode and 3 appointments in cozy mode. The remaining appointments can be accessed with a # More link. In month view, all-day appointments look and behave like regular appointments.

Month view
Month view

You can also create custom views by setting a different number of visible columns in the grid. We only recommend doing this if your use case really requires it. You must also ensure that any custom views are responsive. For anything over 7 days, provide an alternative view for size S.

Custom view 10 days - size L
Custom view 10 days - size L
Custom view 3 days - size S
Custom view 3 days - size S
Developer Hint
If no view is set by the application developer, the single planning calendar renders the week view. If the application developer sets only the day view, the week view is not visible.

4. Navigation

The navigation area contains back and forward arrows, the Today button, a date interval link, and the date strip. Clicking the Today button takes the user to the period containing the current day.

5. Date strip

The date strip is the horizontal axis of the calendar grid, showing the currently visible day or days. Non-working days are a darker color.

6. All-day appointment

All-day appointments are appointments that take up 24 hours. They are located in a dedicated area below the date strip and above the first hour of the timeline.

The option to create all-day appointments must be added at application level. Consider using a switch or checkbox that automatically sets the start and end time of the appointment to 00:00. We recommend reflecting this in the UI for creating the appointment as well. For example, offer a date picker instead of a date/time picker for selecting the start and end of the appointment (as shown in the sample dialog).

There is no limit of the height of the all-day appointments area. However, if your use case involves a lot of all-day appointments (and their area takes up most of the screen), consider using the planning calendar instead.

7. Timeline

The timeline is the vertical axis of the calendar grid, showing the hours.

8. Appointment

Each appointment can have an icon or image, a title, and a subtitle. If there is not enough horizontal space for the text, it is truncated. If an appointment has an icon, the icon remains visible as long as there is space for it, even if that does not leave enough space for the title. If there is not enough vertical space, the subtitle is not shown.

Appointments vary in height, depending on their duration, and in width, depending on how many appointments take place simultaneously. The minimum height of an appointment corresponds to a 30-minute appointment.

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

9. Calendar grid

The calendar contains the appointments and all-day appointments, and is controlled by the currently selected view. Non-working days have a darker background color in the calendar grid.

10. Now marker

The now marker is a horizontal line through the calendar grid, which indicates the current time. The current time is visible on the timeline. If the current time falls within 15 minutes of a full hour, it replaces the full hour.

Appointment structure
Appointment structure
Now marker - Current time replaces the full hour
Now marker - Current time replaces the full hour

Behavior and Interaction

Date Picker

The visible period is indicated with the date interval link in the navigation. Clicking the link opens a date picker, which helps the user to navigate quickly to a specific day or week.

Creating an Appointment

We recommend offering a Create action in the toolbar.

The UI for creating the appointment must be implemented at app level. The control provides only the underlying functionality for creating appointments. For most use cases, a dialog works best and is recommended (see sample dialog below).

Viewing Appointment Details

The UI for viewing appointment details must be implemented at app level. The control provides only the underlying functionality for displaying appointment details. We recommend using a popover to keep the context for the user (see sample popover below).

Working Hours

You can opt to set working hours in the single planning calendar (properties: startHourendHour). The non-working hours then have a different background and can be hidden (property: fullDay). You can also give the user the option to toggle between working and non-working hours. We recommend offering a toggle button in the toolbar (the button must be added by the app team).

Sticky Header

To keep the context when the user scrolls down the calendar, the header area of the single planning calendar can remain fixed at the top of the screen (property: stickyMode).

At app level, you can choose to have the entire header area sticky (value: All) or only the Navigation area (value: NavBarAndColHeaders).

Drag and drop

You can enable drag and drop for moving appointments (property: enableAppointmentDragAndDrop). Moving an appointment changes its start and end times (for example, if an appointment is scheduled from 1:00-2:00 PM, the user can drag it and change the time slot to 2:00-3:00 PM). When dragged, the appointment is shown as a ghost element on the mouse cursor. A placeholder indicates the target drop area.

Appointments can also be dragged from or to the area for all-day appointments. When the user drags an all-day appointment to the planning area, a placeholder shows the duration of the appointment after dropping (default = 1 hour). Similarly, dragging a regular appointment to the all-day appointments area transforms it into an all-day appointment (default = 1 day).

For desktop devices, you can also enable the following options:

  • Allow users to create new appointments by clicking, dragging, and releasing on an empty space in the content area (property: enableAppointmentsCreate).
  • Allow users to change the duration of an appointment by clicking and dragging one side of the appointment (property: enableAppointmentsResize).
Drag and drop
Drag and drop
Drag and drop into the all-day appointments area
Drag and drop into the all-day appointments area
Drag and drop from the all-day appointments area
Drag and drop from the all-day appointments area

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

Visual Filter Bar

The visual filter bar offers a unique way of filtering large datasets through visualizations. This helps users to recognize facts and situations, while reducing the number of interaction steps needed to gain insights or to identify significant single instances.

The visual filter bar allows users to combine measures with filter values. For example, a “Product” might have the filter value “Product Name” and the measure might typically be “Revenue”, “Cost”, or “Quantity”. If you opt for the measure “Revenue”, the chart would show the “Revenue by Product”, enabling the user to filter the data by choosing a particular product name and its revenue.

Chart visualization increases the joy of use and helps users to see relevant data more quickly. For filtering, the visual filter bar uses all of the three types of interactive chartbar chartline chart and donut chart.

Visual filter bar - Size L
Visual filter bar - Size L

Usage

Use the visual filter bar if:

  • You are using analytical list page floorplan.
  • Users need to see both the result and the direct impact of their filter settings in a chart representation.
  • You would like to give users a condensed overview of the data in the dataset.

Do not use the visual filter bar if:

  • You are not using the analytical list page floorplan.
  • Users are not interested in seeing the impact or their filter settings directly in a chart representation.
  • Users are not interested in a condensed overview of the data in the dataset.

Responsiveness

The visual filter bar itself is fully responsive. For overall responsiveness within the analytical list page, see the Analytical List Page article.

Layout

The visual filter bar is a composite control built with other responsive controls, such as the header container and the interactive charts. It is used in the header area of the analytical list page, which incorporates the dynamic page layout.

Collapsed Visual Filter Bar

The collapsed visual filter bar takes up less space, leaving most of the screen for displaying 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 the header. If required by the use case, you can expand the filter bar by default.

On desktop and tablet devices, the collapsed filter bar shows a summary of the filters currently applied. The format of the summary text is:

Filtered By (number of filters): <comma-separated list of the filters currently applied>
Example: Filtered By (2): Country/Region, Product

Up to 5 filters are listed. If more filters have been applied, an ellipsis (…) appears at the end of the string. If no filters have been applied, the summary text is Not Filtered.

Expanded Visual Filter Bar

The expanded visual filter bar also shows a user-defined filter subset of the selected variant. The Adapt Filters link opens the visual filter dialog, where the user can add or hide visual filters. The switch button on the top right switches between the visual filter bar and the standard (input-based) filter bar. The Go button triggers the filter. Note that the Go button is only shown in manual update mode.

Structure

In order to achieve filtering through visualization, the visual filter bar uses interactive charts. Currently, three interactive chart types are available: bar chartline chart, and donut chart. Each chart has a dedicated area for the chart title, the (x) link showing the number of applied filters, and the value help icon  . When the user clicks the (x) link, a popover containing the selected filter values appears. The value help icon opens a value help dialog.

Filter Title Area

In addition to the chart title, the filter title area also contains a value help icon  with (x) indicator, where “x” stands for the number of applied filters. Clicking the icon opens the value help dialog. The value help dialog can be replaced with the select popover icon  .

Use the following naming convention for the filter title, using title case: <Measure Name> by <Dimension Name> | <Scale Factor> <Unit of Measure>. For example, Project Costs by Project | K EUR, Sales Volume by Commodity | M PC.

Visual filter bar - Title area
Visual filter bar - Title area
Visual filter bar - Title area with selected filter values
Visual filter bar - Title area with selected filter values

Bar Chart

The interactive bar chart in the visual filter bar can display only three bars. Based on the measure, they can be sorted ascending or descending. This makes it easy to compare the items and see the highest and lowest values.

Visual filter bar - Interactive bar chart
Visual filter bar - Interactive bar chart

Line Chart

The interactive line chart is used to display variations over a specified period of time. This chart is only used for displaying a time series and can contain only the first or last six time points (for example, last six days, last six months, and so on). 

Do not use a line chart to show categories. Instead, use a bar chart.

Visual filter bar - Interactive line chart
Visual filter bar - Interactive line chart

Donut Chart

The interactive donut chart is best used to display up to three slices. Use this chart if the exact value of each slice is not needed for filtering.

In the visual filter bar, only the top or bottom two values are shown; the rest are aggregated into the Other section.

Visual filter bar - Interactive donut chart
Visual filter bar - Interactive donut chart

Visual Filter Selections

Any data point or segment selected in a chart remains selected when the user changes the measure, chart type, or sort order in any of the charts.

If a selected record falls outside the top or bottom three records being displayed, the (x) status above the chart shows the number of selected records.

Developer Hint

Do not bind a single visual filter (chart) to more than one ID. This will lead to an incorrectly derived item count in the (x) link. Define separate visual filters instead. If this split is not desired, create a calculated column (dimension) in the back end to represent this combined ID.

Don't
Don't use a relative format for time
Don't use a relative format for time
Do
Use titles that give context
Use titles that give context
Do
Add the year in the title if you display only 4 quarters
Add the year in the title if you display only 4 quarters

Visual Filter Dialog

The filter dialog is launched by clicking the Adapt Filters (number of applied filters) link in the upper right filter area. In the filter dialog for visual filters, the user can choose which filter fields are shown in the visual filter bar.

In this dialog, the user can make the following changes:

  • Add visual filters
  • Delete visual filters
  • Hide visual filters in the visual filter bar
  • Search for visual filters
  • Change the sort order of each visual filter
  • Change the chart type of each visual filter
  • Switch to other measures in the visual filter display

The footer toolbar at the bottom of the dialog provides the following functions:

  • Save: Saves your modified filter set variant. 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 use case.
  • Go: Applies the selected filter set.
  • Clear (optional): Clears all filters. Only use this button if it fits the app use case.
Visual filter dialog
Visual filter dialog

Visual Filter Configuration

In the filter dialog, users can configure individual visual filters using the icons in the filter title area:

  • Change the sort order   (not supported for line charts)
  • Switch to a different chart type  
  • Choose between different measures
Visual filter configuration - Sort, chart type, measure
Visual filter configuration - Sort, chart type, measure

Behavior and Interaction

Unlike micro charts, the charts in the visual filter bar are interactive. If you are using live update mode, selecting a filter value triggers data filtering in the content area. Both single and multiple selection are supported.

Selecting Filters

In the visual filter, you can make a selection by clicking a chart value. To deselect it, you can either click the same value in the chart again, or click the (x) link showing the number of selected filters, such as (1).

Any data point selected in a chart remains selected, even if the user selects a data point in another chart. Filter values also react to each other.

If a selected record in a chart falls outside the displayed filter values, the selection is visible in the (x) link above the chart, where (x) represents the number of selected records.

Users can select more filter values with the value help or select popover.

Personalizing the Visual Filter Bar

Add Visual Filter

Users can add more visual filters via the visual filter dialog. The additional filter groups appear below the Basic filter group, which contains the standard filters for the application. While the Basic filter group is always visible, the additional filter groups are initially collapsed.

The More (x) link in the filter group header indicates the number of filters that have not yet been added, for example More (2). Clicking this link opens a dialog for selecting the additional filter. Once a filter has been selected, it displays under the group header in the visual filter dialog, and the user can customize the individual filter settings (sort order, chart type, measure, display in the visual filter bar).

If all filters in a group have already been added in the visual filter dialog, the More (x) link label in the filter group title switches to Change Filters.

Hide Visual Filter

Users can hide a filter 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

Live Update / Manual Update

The visual filter bar is available in two modes: live update and manual update. In both modes the visual filter charts refresh based on the selection.

Live Update

In live update mode, the filter bar reacts instantly to every input change. Because the content area updates automatically whenever the user changes a filter selection, the Go button is not necessary, and is not shown.

Visual filter bar - Live update mode
Visual filter bar - Live update mode

Manual Update

In manual update mode, the filter results are only updated when the user clicks the Go button that is shown in manual mode. Pressing ENTER on the keyboard also triggers the filter.

Visual filter bar - Manual update mode
Visual filter bar - Manual update mode

Recommendation 

In general, use live update mode, which is more convenient for users. However, consider using manual update mode if the user has to configure multiple filters to obtain a useful result set, or if you expect the resulting traffic to be excessively high.

Chart Types

Choosing the right chart type as a representation for a particular filter will not only increase the joy of use but also will convey the right information to the user. Inappropriate chart types can mislead the user during the filtering process.

In the visual filter bar, you can choose between three interactive chartsbar chartline chart, and donut chart.

Recommendation

  • If you expect users to be working with a large number of datasets, and your scenario does not depict time periods, consider using a bar chart.
  • If you want to measure trends and changes over time when filtering, consider using the line chart.
  • If your scenario requires filtering by parts of a whole and has only a small number of datasets, consider using the donut chart.

Filter Selection

In the visual filter, users can make a selection by clicking a chart value or by using the value help to select data points that are not visible. Depending on the number of available data points, you can use the value help or the select popover.

Recommendation

If your scenario involves filtering 200 or more filter values, consider using the value help. For filtering less than 200 values, we recommend using the select popover.

Scaling Factor

Always use a scaling factor to display values larger than 1000. The scaling factor is usually displayed in the interactive chart header. Do not repeat the scaling factor inside the chart itself.

Recommendation

Due to the limited space inside the chart, we recommend showing a maximum of 3 digits before the decimal point.

Visual filter bar with scaling factor (M)
Visual filter bar with scaling factor (M)

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

When suggestions are turned on, the suggestion list displays differently depending on the device type.

Size S (Smart Phones)

Clicking the search field opens a new full screen dialog in which items can be selected from a list of suggestions.

Size S
Size S

Size M (Tablets)

Suggestions are shown below the search field.

Size M
Size M

Size L (Desktops)

Suggestions are shown below the search field.

Size L
Size L

Types

SAP Fiori comes with two different search types.

  1. The manual search is triggered explicitly after the user enters text in the search field and clicks 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. There is a default delay of 400 ms before sending the search data to the back end. This ensures better performance and optimizes user experience. 

Queries that are entered are used to search the back-end 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 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 the “X” icon  ) 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.

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

Properties

The following methods are important.

For the live search:

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

For the manual search:

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

If a Refresh button is needed:

To show the Search button:

To ensure the focus is set to input:

If the search is triggered automatically when the value of the field is changed (unlike the liveChange event, the change event is not fired for each key press):

  • attachChange(oData?fnFunctionoListener?) Attach event handler fnFunction to the change event of this sap.m.SearchField.
  • detachChange(fnFunctionoListener) Detach event handler fnFunction from the change event of this sap.m.SearchField.
  • fireChange(mArguments?) Fire change event to attached listeners.

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

Table Toolbar

The table toolbar always appears above the table. The control is used for key actions that impact the entire table.

Usage

Use the table toolbar if:

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

Do not use the table toolbar if:

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

Responsiveness

To enable responsiveness, use the overflow toolbar control. For more information, see Toolbar Overview – Responsiveness.

Components

The table toolbar can contain several components, including a title and several types of button. Actions are grouped by the following action types:

  • Finalizing actions, such as Save or Cancel. Finalizing actions are app-specific and are used only if the table is editable.
  • Business actions, such as Edit or Create. Business actions can be app-specific or general object management actions.
  • Actions for managing the content, such as Sort or Filter. These settings are also known as “view settings”.
  • Generic actions, such as Export to Spreadsheet.

Between the groups, add a separator line.

The following content can be part of the table toolbar. Use only the content your users really need. For the remaining content, keep the order shown below:

  • Title
  • Variant management or content switch (for example, as used to switch between multiple views in a list report)
  • Search
  • Finalizing actions:
    • Save
    • Cancel
  • Business actions: Use this action type for app-specific actions. This group contains:
    • App-specific business actions
    • Actions for object management
      • Create (for new items) or Add (for existing items)
      • Edit
      • Delete (if the object itself is deleted) or Remove (if the reference to an item is removed)
    • Paste

The order of actions in this group is not “fixed”. Place the most important action first, followed by the second most important action, an so on. Try to keep Create/Add, Edit, and Delete/Remove together, but only if this is meaningful in your app.
Exception: Keep Paste as the last action in this category.

All possible components in the correct order
All possible components in the correct order

Behavior and Interaction

App-Specific Business Actions

If needed, you can define your own actions for the app. In this case, use text-only buttons with a short, unambiguous text for the action the button performs. A button text is usually a single-word verb (for example, Share). Note that text strings can be longer in other languages.

Table toolbar with app-specific buttons
Table toolbar with app-specific buttons

Title

A title provides a short, meaningful summary of the content, mostly in a single word. To display a title, use the title control.

In addition, the title can be followed by an item counter (the number of items in parentheses).

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

Title with item counter in the table toolbar
Title with item counter in the table toolbar

Variant Management

In tables, a variant stores all the settings that define the table view, such as the column layout, column visibility, sorting, filter settings, and grouping. The variant management control enables users to load, save, and change variants. In most cases, variant management replaces the title.

Variant management in the table toolbar
Variant management in the table toolbar

Title and Variant Management

If you need both a title and variant management, place the variant management control directly after the title. Use a separator between the title and variant management.

Since using both controls often leads to truncation problems, this pattern is not recommended.

Title with variant management
Title with variant management

Content Switch

To switch between different predefined views, use a select control or a segmented button. The content switch replaces the title and the variant management control. In the rare case that the content switch is shown together with a title, the content switch follows the title.

A predefined view contains settings for sorting, filtering, grouping, column layout, and column visibility. Nevertheless, in most cases, the content switch is just used for different filter settings like All, Mine, and Others. In this case, make sure that the content switch doesn’t interfere with other filter settings. For example, remove the corresponding filter from the filter bar. If possible, include an item counter per view.

Another common pattern for content switches are views like By X, and By Y, which are usually defined using group settings.

Use the segmented button and the select control as follows:

  • For a limited set of views (2-3), use the segmented button for desktop and tablet devices. Replace it with a select control if there is not enough screen space.
  • If the number of views can change or is larger than 3, use the select control.

For more information, see multiple views for list reports.

Segmented button with a counter
Segmented button with a counter
Segmented text button to switch content
Segmented text button to switch content
Select control to switch content
Select control to switch content

Search

For tables with a large number of items, consider adding a search field. Use a search field only if there is no other way to search within the table (for example, if there is no additional filter bar).

Place the search field on the right side of the toolbar. Since the search field cannot be moved into the overflow menu, always provide a minimum width.

Ideally, search for results in all columns. As a minimum, search in all currently visible columns.

For more information, see Search.

Search in the table toolbar
Search in the table toolbar

Edit

There are several options for editing a table:

Edit a Single Item

To allow the user to edit a single item, show an icon-only Edit button at the end of the item (depending on the table control, use sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive; or row actions). The user can click the button to trigger the edit event. Use this event to make the item editable.

Editing a single item
Editing a single item

Mass Editing

See: Mass Editing

Edit the Whole Table

To let the user edit a whole table, use a text-only Edit button. When the user triggers the edit action, switch the table to edit mode. In edit mode, do not show the Edit button and add the finalizing actions Save and Cancel instead. Remove any actions that are meaningless in edit mode. Keep the view settings available.

See also: Manage Objects.

 Table in display mode with 'Edit' as the most important action
Table in display mode with 'Edit' as the most important action
Table in edit mode
Table in edit mode

Create / Add

Use a text button for Create or Add actions. If the Create or Add action is a main function, never move it into the overflow.

See also: Manage Objects.

Table toolbar with 'Create' button
Table toolbar with 'Create' button
Table toolbar with 'Add' button
Table toolbar with 'Add' button

Delete / Remove

Use a text button for Delete or Remove actions. In most cases, Delete is used together with Create, while Remove is used together with Add.

If the Delete or Remove action is a main function, never move it into the overflow.

See also: Manage Objects

Table toolbar with 'Delete' button
Table toolbar with 'Delete' button
Table toolbar with 'Remove' button
Table toolbar with 'Remove' button

Sort, Filter, Group

When the user chooses one of these actions, open the view settings dialog or the P13n Dialog with only the corresponding settings.

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

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

Ensure a consistent user experience. When a user reopens the app and if variant management is not used, show the table with the same view settings that were last defined by this user.

For more information, see Table Personalization.

Triggers for the different view settings (sort, filter, and group)
Triggers for the different view settings (sort, filter, and group)

Column Settings

Use the table personalization dialog or the P13n Dialog for adding, removing, and rearranging columns.

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

Ensure a consistent user experience. When a user reopens the app and if variant management is not used, show the table with the same column settings that were last defined by this user.

For more information, see Table Personalization.

Table toolbar with 'Column Settings' button
Table toolbar with 'Column Settings' button

Export to Spreadsheet

The Export to Spreadsheet action allows the user to export table rows and is represented by an icon-only menu button.

Table toolbar with the 'Export to Spreadsheet' menu button
Table toolbar with the 'Export to Spreadsheet' menu button

Print

The action for printing table items is represented by an icon-only button.

Table toolbar with 'Print' button
Table toolbar with 'Print' button

Maximize / Minimize

To allow the user to show the table in full screen mode (property: ShowFullScreenButton), show the   Maximize button.  The user can exit the full screen by clicking the   Minimize button.

Table toolbar with 'Maximize/Minimize' button
Table toolbar with 'Maximize/Minimize' button

View Switch

View switches are right-aligned in the toolbar and allow the user to switch between different chart types and different controls for displaying items (for example list, responsive table, grid list). Provide the view switch if a chart relies on subtle color differences or gradients of color. In these cases, users with visual impairments can switch to the table view.

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

Define the number of chart types and switches with care. Offer only chart types that are meaningful for visualizing the respective data and that best assist the user. Ideally, offer no more than three types of visualization.

The sequence of chart type switches is not fixed. Sort them in order of importance.

The chart type currently in use is highlighted. To show this, use a segmented button with icons.

For more information about the icons and the chart types they represent, see Chart Toolbar.

Styles

On the table toolbar, use the following button styles:

  • If the single primary action for the whole page is on the table toolbar, use the emphasized button style.
  • if the single primary action for the whole page is not on the table toolbar, you can still highlight the most important button of the table toolbar by using the ghost button style.
  • For secondary actions and negative path actions, use the transparent button style.
  • For split buttons and menu buttons, use the transparent button style.
  • Do not use semantic button styles on the table toolbar.

For more information, see Button and Action Placement.

Guidelines

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Let the user choose whether to apply the action anyway or cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element States.

Message for an action that applies to a part of a selection
Message for an action that applies to a part of a selection

If the items are still available after the action was applied, keep them selected.

For further guidelines, see Toolbar Overview – Guidelines.

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

Title

The title control is a simple, large-sized text containing additional semantic information for accessibility purposes.

The difference between a title and a manually styled heading is that the title can be used by assistive technologies such as screen readers to create a hierarchical site map for faster navigation.

The title is used, for example, by paneltoolbar, or list components.

Example of a title
Example of a title

Usage

Use the title if:

  • You want to set the title above a table or form.
  • You want to show text in the page header.

Do not use the title if:

  • The text is inside a text block.
  • The text is inside a form element.

Responsiveness

You can define whether the text should wrap or truncate directly (property: wrapping). If hyphenation or truncation is not set, the text of the title is wrapped word by word.

For more information on using wrapping and truncation, see Wrapping and Truncating Text.

Truncated title
Truncated title

Hyphenation

The title control also supports hyphenation for wrapped texts (property: wrappingtype =
Hyphenated). Switching on hyphenation activates it for all languages that have hyphenation support.

Wrapped title
Wrapped title
Wrapped, hyphenated title
Wrapped, hyphenated title

Styles

The actual appearance of the title and the different styles always depends on the theme being used.

The semantic level of the title can be set automatically or explicitly. With the automatic setting (property: level, value: Auto) no explicit level information is written (HTML5 header element). If you want to set it explicitly, use an HTML H1-H6 element (property: level, value: H1-H6).

The level (property: level, value: Auto, H1-H6) and title style (property: titleStyle, value: Auto, H1-H6) can be set independently.

Title with level H1 to H6 and default style
Title with level H1 to H6 and default style

Guidelines

  • When using the title in the dynamic page header, use wrapping in expanded mode and truncation in collapsed mode.
  • In other places, such as toolbars or dialog headers, do not use wrapping. Truncate the title instead.

Properties

The following properties are available:

  • The property text defines the text that should be displayed as a title.
  • The property level (default: auto) defines the semantic level used by assistive technology. The default level can be overridden with H1 to H6 to set the level explicitly.
  • The property titleStyle (default: auto) defines the actual appearance of the title. When you use automatic styling, the appearance of the title depends on the current position of the title and the defined level. This automatism can be overridden by explicitly setting a different style between H1 and H6.
  • The property width defines the width of the title.
  • The property textAlign (default: initial) defines the alignment of the text within the title. Note: This property only has an effect if the overall width of the title control is larger than the displayed 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

Smart Filter Bar

Intro

Information
This article is intended as an aid to designers and developers who want to explore the detail configuration options available for the smart filter bar.

The smart filter bar uses annotations to create a filter bar. It’s a wrapper that analyzes a given OData service and renders a filter bar based on the content defined by the service. For example, the OData service determines whether a field is visible on the filter bar, and whether it supports type-ahead and value help. To configure more settings or overwrite the settings from the OData service, the developer can set additional annotations in an external document (metadata.xml).

The developer can use annotation properties in the classes [external_only]ControlConfiguration and GroupConfiguration to adapt the filter bar for the purposes of the app.

These annotations let you:

  • Determine the type of control (for example, whether a field is shown as a multi-input field or as a date picker)
  • Enable the autocomplete suggestions feature
  • Enable the value help dialog
  • Overwrite settings from the OData service
  • Set custom filter groups
  • Add custom fields
  • Access all settings for the underlying filter bar

You can also use all the configuration options described here in the smart filter bar for the list report SAP Fiori element.

Warning
Most of the attributes/properties are not dynamic and cannot be changed once the control has been initialized.

Usage

Use the smart filter bar if:

  • An OData service is available.
  • You want to develop quickly and efficiently.

Do not use the smart filter bar if:

  • You need to make extensive changes to the filter bar.

Components

You can use the annotation properties listed below to influence how filters are rendered in the expanded filter bar and in the filter dialog.

Expanded Filter Bar

Properties for the expanded filter bar
Properties for the expanded filter bar

1 enableBasicSearch
Defines whether the filter bar includes a basic search. By default, the basic search is not included.

2 FilterRestrictions/NonFilterableProperties
Defines whether a property is available as a filter criterion.

3 FilterRestrictions/RequiredProperties
Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

4 ValueList
Contains annotations that provide information for rendering a value help list that has been set for a property.

5 FilterExpressionType/MultiValue
Defines whether multiple values can be used in a single filter.

6 FilterExpressionType/SingleValue
Restricts the filter to allow only one value entry.

7 LineItem/Label
A short, human-readable text for the filter name.

8 FilterExpressionType/SingleInterval
Restricts the filter to a specified interval, such as a date interval

8 insertDefaultFilterValue
Inserts a default filter value into the aggregation defaultFilterValues.

9 liveMode
Defines whether the expanded filter bar is shown in live mode (no Go button) or in manual mode. By default, the filter bar is shown in manual mode.

 

Filter Dialog

Properties on the filter dialog
Properties on the filter dialog

1 FilterRestrictions/RequiredProperties
Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

2 FieldControlType/Hidden
Defines whether the filter is initially visible on the expanded filter bar.

SelectionFields
Defines whether a filter belongs to the basic group. All filters in the basic group are initially visible on the expanded filter bar.

4 FieldGroup
Defines whether a filter field is initially shown on the filter dialog, and which group it belongs to.

5 FilterRestrictions/NonFilterableProperties
Defines whether a property is available as a filter criterion.

6 LineItem/Label
A short, human-readable text for the filter name.

Fiscal annotations

As an example, the smart filter bar supports fiscal annotations, like i.e. for fiscal period / data / time information. Such annotations guarantee the correct rendering of such values.

Smart filter bar with filters based on fiscal annotations
Smart filter bar with filters based on fiscal annotations

Recently entered values

The smart filter bar provides a history of recently entered values in the smart filter field. When focusing a field, an app can provide a small amount of recently used values. They are shown below the recommended items, which could appear at the same time. All values are shown if the drop-down is opened. Start typing will work like before, where the recently used values are filtered accordingly.

IN / OUT Parameter

In the smart filter bar, a drop-down or suggestion list can only contain a sub-set of items in case a dependent filter is set (IN parameter). It is also possible that selecting a value in a drop-down or suggestion list fills the current plus additional filter fields (OUT parameter).

Data Types

The smart filter bar analyzes and interprets the metadata provided by the OData service. This allows you to create complex UI entities, and to automatically add fields offered by the OData service to the filter bar as editable input fields. (Note that only fields marked with sap:filterable are added automatically.)

The tables below tell you which input controls are used for the key data types. 

General Data Types

DataType ODataMetadata Additional Configuration Edit type Display type Notes
* * Input Text
DateTime sap:display-format=”Date” DatePicker Text
Decimal Precision=”3″ Scale=”0″ Input Text
All Input (with VHD) Text If a matching ValueList annotation is found, the ValueHelp for the Input is enabled.
A ValueHelp Dialog is created automatically, based on the data in the ValueList annotation.
All
sap:semantics=”fixed-values” on the ValueList entity
ComboBox Text If a matching ValueList annotation is found, and the ValueList entity has the semantics=”fixed-values”, a dropdown list is shown.

Filter Bar-Specific Data Types

Input Type sap:filter-restriction display-format     hasValueHelpDialog controlType Resulting Control Type
* * controlType/filterType is specified As specified in additional configuration
DateTime “interval” “Date” NA Date Range Selection
DateTime “anything other than interval” or empty “Date” NA Date Picker
String “single-value” “true” / none Input Field With Value Help Dialog
(with typeAhead according to hasTypeAhead flag)
String “single-value” “false” not specified/input Input Field
(with typeAhead according to hasTypeAhead flag)
String “single-value” “false” dropDownList; hasTypeAhead is not considered here ComboBox
* “single-value” Input Field
String empty or no filter-restriction “true” / none Multi Input Field with Value Help Dialog
String “multi-value” “true” / none If no VL Annotation is found – only show the range selection part
String “multi-value” / empty “false” If no VL Annotation is found – hide the ValueHelpDialog icon
String “multi-value” / empty “false” dropDownList MultiComboBox
* “multi-value” Input Field
* “interval” NA A single Input Field that allows the “-” shortcut notation for intervals

Guidelines

Reduced set of table columns for the tabular suggestion

You have the option to define different columns in the table of the Value Help Dialog and the suggestion list of the Smart Filter Bar.

In the , each parameter can be statically annotated as important using the <code>Importance</code> annotation with EnumMember set to High:

<Annotation Term="com.sap.vocabularies.UI.v1.Importance"
        EnumMember="com.sap.vocabularies.UI.v1.ImportanceType/High" />

In the suggestion list only the important parameters are displayed as columns, while in the table of the Value Help Dialog all of the parameters are displayed.

The Importance annotation is optional – if omitted all of the parameters are displayed in both table of the Value Help Dialog and the suggestion list of the Smart Filter Bar.

Formatting option for negative numbers

A new OData type NumericText improves the display-format=”NonNegative” of numeric fields. All values containing only 0, for example, „0“, „00“, „000“ etc., are interpreted and displayed as empty.

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. Do not use the label control to display the data (for example, in display-only forms).

Required/Optional Fields

In edit mode, the label indicates whether an entry is mandatory (“required”) or optional.

If a field is required, an asterisk is shown after the label text. The asterisk is only visible in edit mode, and not in display mode.

Developer Hint
To indicate that a field is required, set the required property to true.
Required label in an editable environment (horizontal layout)
Required label in an editable environment (horizontal layout)
Result of a required label in a display-only environment
Result of a required label in a display-only environment
Optional label in an editable environment (vertical layout)
Optional label in an editable environment (vertical layout)
Result of an optional label in a display-only environment
Result of an optional label in a display-only environment

Styles

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

Wrapping

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

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

Developer Hint

The boolean wrapping property for the sap.m.Label control determines whether or not the text wraps .
Note: Only use this property in forms.

Hyphenation

The label control also supports hyphenation for wrapped texts (property: wrappingtype = Hyphenated). Switching on hyphenation activates it for all languages that have hyphenation support.

Wrapping label
Wrapping label

Guidelines

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

Exceptions

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

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

Resources

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

Elements and Controls

Implementation

Input Field

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

Usage

Use the input field if:

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

Do not use the input field if:

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

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 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 by 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 implement format validation. If binding is used, validation is carried out by the model, but error handling must still be implemented on the UI side.

Text (default)

Input type text – Keyboard layout on a smartphone
Input type text – Keyboard layout on a smartphone

Number

Input type number – Keyboard layout on a smartphone
Input type number – Keyboard layout on a smartphone

Email

Input type email – Keyboard layout on a smartphone
Input type email – Keyboard layout on a smartphone

URL

Input type URL – Keyboard layout on a smartphone
Input type URL – Keyboard layout on a smartphone

Telephone Number

Input type telephone number – Keyboard layout on a smartphone
Input type telephone number – Keyboard layout on a smartphone

Password

Input type password – Keyboard layout on a smartphone
Input type password – Keyboard layout on a smartphone

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

Examples of input with different number masks
Examples of input with different number masks

Behavior and Interaction

Entering Text Using the Autocomplete Feature

Have a look at the interaction flow below:

Entering Text Using the Value Help Dialog

Have a look at the interaction flow below:

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

Styles

An input field can have five value states: default (neutral), warning, error, success, or information.

Default
Default
Error
Error
Information
Information
Warning
Warning
Success
Success

Properties

Value State and Value State Message

The input control offers the five value states listed below. For the error, warning, and information 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.
  5. Information

For more guidance on when to use which state, see How to Use Semantic Colors.

Default
Default
Error
Error
Information
Information
Warning
Warning
Success
Success
Warning value state with a long, wrapping text
Warning value state with a long, wrapping text

Required

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

Required input field
Required input field

Maximum Length

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

Placeholder

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

Placeholder
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. Instead of defining a fixed width, we recommend 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. Enabled: This is the default setting.
  2. Read-only: The input field isn’t 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 editing isn’t possible (for example, because the user isn’t authorized to make changes).
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

Value Help

To help the user find the correct value, you can enable the value help option (propertyshowValueHelp). 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). 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. In this case, the values are automatically transformed into conditional expressions. For example: Copying values “1234” and “5678” leads to the token generation “=1234” and “=5678”. Additionally, these values are shown in the conditions tab of the value help dialog.

Input Assistance

Intelligent systems can help users by recommending appropriate content or suggesting an action or input the user may “prefer”. The system assists the user by entering data or filtering data. Typical examples might be a search phrase suggestion, an appropriate form template, or a set of suggested default values for certain fields, based on the user input and interaction history.

For more information, see Designing Intelligent Systems – Input Assistance.

Autocomplete Suggestions

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

As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. The user can accept the autocompleted value by pressing ENTER. The autocomplete property is set by default if suggestions are available, but can also be switched off.

Warning
The typeahead input feature is not available on Android devices

Single Value with Autocomplete

Single-value autocomplete displays a list of suggestions with one left-aligned value. As a base for the aggregation suggestionItemssap.ui.core.Item is used.

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

See this 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 a customer and an ID.  As a base for the aggregation of suggestionItemssap.ui.core.ListItem is used.

The text property is displayed first, and is left-aligned. The additionalText property is right-aligned. The first text property is autocompleted in the input field.

Use the two-value autocomplete feature if you want to search by two attributes. This ensures that the search is carried out for both attributes.

See this 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. Use the tabular autocomplete feature if you need to display more than two attributes.

For input fields in a tabular view, we recommend using a maximum of 4 columns. Focus on columns that are really relevant for the use case.

To use the tabular autocomplete feature, use the suggestionColumns aggregation to define the columns and the correct responsive behavior for the pop-in. Define appropriate responsive behavior for sizes S and M. 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:

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.

See a live example of tabular autocomplete suggestions.

Tabular autocomplete
Tabular autocomplete

Grouping

You can group the items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

Input with grouped suggestions
Input with grouped suggestions
Input with grouped tabular suggestions
Input with grouped tabular suggestions

Guidelines

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

Maximum Columns

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

Maximum Length

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

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

Placeholder

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

Description

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

Width

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

Editable and Enabled States

Editable

Property settings: editable = true, enabled = true

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

Not Editable

Property settings: editable = false, enabled = true

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

Disabled

Property settings: editable = not relevant, enabled = false

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

Text Align

Align left if:

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

Align right if:

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

Value Help

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

Use this option in combination with the autocomplete suggestion feature.

When the user clicks 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.

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 fieldcombo boxmulti-combo box, and select controls.

Input field – New action
Input field – New action
Input field – Edit action
Input field – Edit action

Resources

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

Elements and Controls

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 the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show multiple 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:

  • You plan to use only one single tab.

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 – Text tabs
Responsiveness – Text tabs
Responsiveness – Icon tabs
Responsiveness – Icon tabs

In addition to the responsive overflow behavior, the icon tab bar can be forced into compact mode or even react dynamically to the application’s global density setting. See the Tab Density section for details.

When the screen space does not allow to show all tabs on the main tab bar, an overflow appears on the far right, containing all remaining tabs that do not fit on the screen.

Responsiveness – Overflow
Responsiveness – Overflow

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 next to 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 UpperCase property is disabled and that you enter the labels in title case (for 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.

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), since 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.

Hierarchies

The tab bar supports hierarchies, allowing multiple tabs underneath one main tab. This way, you can group several tabs together, with the main tab acting as a headline.

Subtabs

The example on the right shows the main tab Notes with two subtabs, Internal and External, with no specific hierarchy except for their order.

Types – Subtabs
Types – Subtabs

Nested Tabs

Nesting allows deeper hierarchies with indentations to indicate the level of each tab.

Types – Nested Tabs
Types – Nested Tabs

Behavior and Interaction

Clicking a Tab

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

Optional behavior: If the user clicks a tab that is 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”).

Changing the Order of Tabs

Applications can allow users to rearrange the tab order when working in a desktop environment (property: enableTabReordering). If this feature is enabled, users can use drag and drop to reorder tabs, either directly on the tab bar or inside the overflow menu. It is also possible to drag and drop tabs from the tab bar to the overflow menu and vice versa.

Please note that this feature is not available for tabs as process steps to ensure that consecutive steps do not get mixed up.

Styles

Tab Density

The default responsive design of the icon tab bar applies to both compact and cozy modes. However, in addition to this responsive behavior, the control can be forced into a compact mode, or even react dynamically to the application’s global density setting. This feature can be used to:

  • Save vertical space on the page (applies to both text and icon tabs)
  • Save horizontal space (icon tabs only; this is especially helpful when there are many tabs)
  • Generally use less space on mobile devices
  • Reduce noise when there are already more important visual elements on the screen (primarily icon tabs)

The property for the override is called tabDensityMode, which can be set to “Cozy”, “Compact”, or “Inherit”. “Cozy” is the default setting that renders the control in its regular dimensions. “Compact” reduces the control’s height and icon sizes (if applicable), even if there would be enough space for the cozy design. “Inherit” instructs the control to follow the global density mode defined for the application. For backward compatibility, the default setting is “Cozy”.

The following image shows some types of tabs with their default style (cozy, left) and the reduced density mode (compact, right).

Style – Tab density
Style – Tab density

Colors

The two different styles (round tabs and text only) are discussed in the Types section. In both cases, you can use semantic colors to give users additional orientation.

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. For more information, see How to Use Semantic Colors.

Developer Hint
To apply semantic colors to the icons and the text-only tabs, you can use the property for sap.ui.core.IconColor.

Example

In the example below, one step in the process 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

Implementation

Avatar

The avatar is a control for displaying images. These can be user profiles, user initials, placeholder images, icons, or business-related images, such as product pictures.

Usage

Use the avatar to display:

  • An image, initials, or placeholder for a user
  • Standardized images for business-related content (such as products, parts, product and company logos, ad campaign images, …)
  • Icons
  • Images with a transparent background
  • Placeholder images

Do not use the avatar if:

  • You want to include an image for any other use case. Instead, use the image control.
  • You want to display pictures in a carousel. Instead, use the carousel control.
  • You want to show an interactive icon. Instead, use the button with an icon inside.
Examples of a user image, user initials, and standard user placeholder icon
Examples of a user image, user initials, and standard user placeholder icon
Potential product image and product image placeholder
Potential product image and product image placeholder
Icon
Icon

Responsiveness

The avatar control is adaptive and has five predefined sizes. These are the same for both compact and cozy form factors:

 

Size rem Use for images in…
XS 2 rem Table list items
Card list items
S 3 rem Card headers
Card list items
M 4 rem App headers for small screen sizes
L 5 rem App headers for normal screen sizes
XL 7 rem App headers for large screen sizes

If your use case requires it, you can also set a custom size.

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

Image Fit

You can use the imageFitType property to specify how images fit to the avatar. There are two options: Cover (default) and Contain.

Cover

The size of the image is scaled up to completely cover the control area. As a result, parts of the image may be outside the shape.

Use the Cover fit type if the focal point is in the center of the image.

Contain

The image is scaled down to fit into the control area. The entire image is displayed, but might not fully fill the shape. In this case, the control displays a default background color. The image itself is always centered inside the shape.

Use the Contain fit type for product pictures that need to be displayed in full.

Product image with the fit type 'cover' (left) and 'contain' (right)
Product image with the fit type 'cover' (left) and 'contain' (right)

Types

Avatar – User Image, Initials, or Placeholder

An avatar is a visual representation of a user in the digital space. Usually, an avatar displays the user in one of the following ways:

  • A user photo
  • The user’s initials
  • A placeholder icon instead of the user’s personal data (photo or initials)

Always display avatars in a circle. This ensures that all users are represented equally on the user interface.

Initials

User image, user initials, and standard user placeholder icon
User image, user initials, and standard user placeholder icon

The initials stand for the first name(s) and last name(s) of a person – for example, JD for Jane Doe, or MvV for Marjolein van Veen. Which name comes first depends on the language-specific settings.

Initials can have up to three alphabetical characters (A-Z, a-z). If more than 3 initials are required for longer names (such as Anna María Agustí Suárez), the gender-neutral placeholder icon is displayed instead. The placeholder is also used if the three letters don’t fit into the circle (for example, WWW).

Some languages don’t build on an alphabet, or don’t use initials at all. In such cases, the gender-neutral person icon is displayed instead.

User initials with 1, 2, and 3 characters
User initials with 1, 2, and 3 characters

Business Images

Business images display a product, company, object, logo, or other business-related content.

Always use a square for business images.

Examples of product images
Examples of product images

Placeholder for Avatar and Business Images

Placeholder images are used for both avatar and business images when no other image is available.

  • The default placeholder for an avatar is a gender-neutral person icon inside a circle.
  • The default placeholder for a business image is a neutral product icon inside a square.
Default person and product placeholders
Default person and product placeholders

You can specify your own the default placeholder icon for business images.

Always replace the default product icon if there is a more suitable icon for your use case and industry.

Product placeholder images with custom icons
Product placeholder images with custom icons

Placeholder Background

By default, the placeholder background color is set to blue (accent color 6). However, to add more visual variety to the UI, you can change the background color using one of the following options:

  • Accent colors – You can specify one of 10 different accent colors as the placeholder background color.
  • Random color – The control automatically picks a random color from the accent color palette.

All accent colors can be themed.

User initials in all ten accent colors
User initials in all ten accent colors

Placeholder for Decorative Images in the Content Area

Use the background color ‘placeholder’ for decorative images in the content area, such as images in articles or longer descriptions. In these use cases, the primary focus is on the text and the image content is secondary.

Decorative image in the content area
Decorative image in the content area
Placeholder image for secondary content
Placeholder image for secondary content

Images with Transparent Background

You can display images with a transparent background. This can be useful for displaying descriptive illustrations and decorative pictures, for example.

Image with transparent background
Image with transparent background

Icons

You can use the avatar to display non-interactive display icons. Use the background color ‘placeholder’ to display the icon.

If you want to put an action on the icon, use the button with an icon inside instead.

Exemplary icons
Exemplary icons

Badge

If an avatar is clickable, you can show an optional badge and icon.

  • Use a badge to indicate that the avatar is interactive.
  • Use an icon to indicate the action triggered by clicking the avatar.

This feature gives users visual affordance of the available action, and is particularly useful for images.

When you use a badge and icon, always provide a corresponding tooltip for your avatar to indicate the action.

Use the following standard icons and tooltip texts:

 

Icon Tooltip Action
  Edit Image Edit the image. This can include multiple options, such as replacing an image, cropping, visual effects, or taking a new picture.
  Take a Picture Take a photo.
  Zoom In Zoom into the image.
Avatars with badges
Avatars with badges
Avatars with badges and edit (left), camera (middle), and zoom in (right)
Avatars with badges and edit (left), camera (middle), and zoom in (right)

Guidelines

  • If you use a custom avatar size with initials or icons:
    • Make sure that the font size is consistent with the size of the control itself.
    • If your custom size is between two predefined sizes, use the font size for the smaller predefined size.
      Example: If your avatar is 5.5 rem (between sizes L and XL), use the font size for size L (2 rem).
  • Accessibility: Provide an alternative text for each avatar image for cases when the image is not available or can’t be displayed.
  • If the avatar is interactive, provide a tooltip to indicate the action (for example, Edit Image or Take a Picture).
  • Optimize high-resolution images to avoid unnecessarily large files. Large image files can severely impede page performance.
Do
Custom placeholder size with appropriate custom font size
Custom placeholder size with appropriate custom font size
Don't
Custom placeholder size, but icon is too small
Custom placeholder size, but icon is too small

Styles

You can add a very subtle border to the avatar (property: ShowBorder).

Images with optional borders
Images with optional borders

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

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, see 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 – Size S
Header toolbar – Size S
Header toolbar – Size M
Header toolbar – Size M
Header toolbar – Size L
Header toolbar – Size L

Components

The header toolbar can contain the following components:

  • App-specific business actions
  • Generic actions

 

The following actions count as generic:

  • Flag and Favorite
  • Share menu
  • Overflow
  • Paging

Behavior and Interaction

Business 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, Synchronize). Note that translated UIs may increase the length of the text string.

Text vs. Icon Buttons

Use text-only buttons for all business actions (such as Edit and Create).
Use icon buttons only for generic actions (such as  for Share). For icons, always provide a suitable text label as a tooltip.

Business action with icon button in header toolbar
Business action with icon button in header toolbar
Actions in the header toolbar
Actions in the header toolbar

Edit and Delete (1)

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.

Add / Create (2)

Place the Add or Create (item or row) action as close to the content as possible.

If the Add or Create action is a main function, don’t move the action into the overflow.

For more information on when to use add or create, see UI Text Guidelines

Favorite and Flag (Generic) (3)

Users can mark objects as a favorite or flag objects for quick subsequent retrieval. The user does this by clicking the relevant generic Favorite or Flag button in the header toolbar. For more information, see Flag and Favorite.

Share (Generic) (4)

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

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
Open share popover in header toolbar
Open share popover in header toolbar

Overflow (Generic) (5)

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.

The  “” (overflow) button can be used to toggle the overflow menu on and off.

The user clicks 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 with open overflow
Header toolbar with open overflow

Paging (Generic)

Use the paging buttons if you want to navigate to the previous or next object.

Use the following tooltip labels:

  • Icon: Up arrow
    Tooltip label: Previous [Object]
    Example: Previous Purchase Order Item
  • Icon: Down arrow
    Tooltip label: Next [Object]
    Example: Next Purchase Order Item

To avoid translation issues, never use “Next” and “Previous” as standalone labels. Always state the object you are navigating to.

If you are using the Share button, place paging buttons to the right of the Share button.

Paging buttons in header toolbar
Paging buttons in header toolbar

Styles

  • Use button styles only if they help the user, and not for decoration.
  • Use them for primary actions, such as Edit and Create.
  • Use a positive/negative style (property: type = accept or rejector an emphasized style (property: type emphasized).
  • Use only one emphasized button per toolbar and never mix emphasized and semantic buttons.
    Exception 1: Messaging button appears
    Exception 2: Object has been flagged or marked as a favorite

For more information, see Button.

Guidelines

For more information, 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 / Simple Form

Information
This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

Intro

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 labelsinput fieldscheckboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two 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).

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 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 and simple 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 / breakpointLbreakpointXL. 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 and simple 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 and simple 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 and simple 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 and the simple 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 and simple 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)

Column Layout

If you use the default form settings, each form group displays in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right of the screen.

To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns (layout: ColumnLayout).

You can use this option to distribute the content for up to two form groups. As soon as there are more than two form groups, the display reverts to the default layout (one column per form group).

The examples below show how forms with one and two form groups display with and without layout balancing.

One form group with default arrangement
One form group with default arrangement
One form group with balanced column layout
One form group with balanced column layout
Two form groups with default arrangement
Two form groups with default arrangement
Two form groups with balanced column layout
Two form groups with balanced 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.

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.

Label Alignment

  • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
  • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
Information
The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

Unit of Measurement

You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

Unit of Measurement
Unit of Measurement

Amount Alignment

When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

Label

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

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

Input Assistance

Intelligent systems can help users by recommending appropriate content or suggesting an action or input the user may “prefer”. The system assists the user by entering data or filtering data. Typical examples might be a search phrase suggestion, an appropriate form template, or a set of suggested default values for certain fields, based on the user input and interaction history.

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

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

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 go into the overflow last.

App-Specific Actions

If needed, you can define your own action for the app. Use text-only buttons with a short, unambiguous text for the action the button performs. A button text is usually a single-word verb (for example, Save). Note that text strings can be longer in other languages.

Text vs. Icon Buttons

Use text-only buttons for all finalizing/closing actions (such as Save).

Styles

  • Use button styles only if they help the user, and not for decoration.
  • Use the emphasized button for primary actions, such as Save.
  • Use the ghost button style for secondary actions, such as Return, and the transparent button for negative path actions, such as Cancel.
  • Use the semantic button for positive/negative actions (property: typeaccept or reject).
  • Use only one emphasized button per toolbar and never mix emphasized and semantic buttons.
    Exception: Additional messaging button for the message popover.

For more information, see Button and Action Placement.

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 Date

The dynamic date is a smart control that is currently only available in the smart filter bar. When the user enters a value in the date field, it suggests corresponding fixed and dynamic dates. It also offers a value help feature that lets users choose between different time periods and define them further. The list of values offered must be defined by the app.

Information
The dynamic date control can only be used in the smart filter bar. If you are not using the smart filter bar, use the date range selection control instead.

Usage

Use the dynamic date control if:

  • You need flexibility between fixed and dynamic dates.
  • You need dynamic dates that can be saved in the variant management (for example, show values from today regardless of when you open the app).
  • You are using the smart filter bar.
  • The user only needs to select one value.

Do not use the dynamic date control if:

  • Users need to enter a date and a time. In this case, use the date picker or the date/time picker instead.
  • Selecting ranges is not the user’s primary goal. In this case, use the simple date picker.
  • You are not using the smart filter bar.

Responsiveness

The dynamic date control is fully responsive. It provides a touch-friendly screen in sizes S and M (cozy mode) and is smaller in size L (compact mode). For more information on cozy and compact modes, see the article on content density.

Value help for dynamic date range - Size S
Value help for dynamic date range - Size S
Value help for dynamic date range - Size L
Value help for dynamic date range - Size L

Components

The dynamic date consists of two components: the date input field with suggestions, and the value help popover. On all devices, users can either use the input field to type a date, or use the value help button to open the popover.

The two clickable areas of the dynamic date control on all devices
The two clickable areas of the dynamic date control on all devices

Dynamic Date Input Field

The user can type data directly into the input field. Upon user input, a list of suggestions appears.

Value Help Popover

The value help popover offers all available values the user can choose from. Depending on the selected time period, the popover shows different controls. It either shows an input field (1), one or two date pickers (2), a read-only text with the chosen time period and date range (3), or a select control.

The different options for defining time period values
The different options for defining time period values

Values Offered

  • From
  • To
  • Date Range
  • Today
  • Today -X / +Y days
  • Last X days
  • Next X days
  • This week
  • Last week
  • Last X weeks

Offered Values

  • Next week
  • Next X weeks
  • Month
  • This month
  • Last month
  • Last X months
  • Next X months
  • This quarter
  • Last quarter
  • Last X quarters
  • Next quarter

Offered Values

  • Next X quarters
  • First quarter
  • Second quarter
  • Third quarter
  • Fourth quarter
  • This year
  • Last year
  • Last X years
  • Next year
  • Next X years
  • Year to date

Behavior & Interaction

Typing data into the date range input field

The user can type keywords or numbers into the date range input field.  For example, if the user types a number, the system automatically suggests possible dates. All dynamic dates show the actual dates to help the user select the right value.

List of suggestions shown after typed input
List of suggestions shown after typed input

Opening the value help and selecting a time period

Clicking the value help icon opens a popover with additional options for defining the time period. The user can choose from several time periods by clicking the down arrow in the select control. Once a time period has been chosen, the selection box closes.

Opening the value help popover and selecting a time period
Opening the value help popover and selecting a time period

Defining a custom time period (X)

If the user selects a custom time period with “X”, such as Last X days, the control shows a simple input field for entering the number. The text in the date input field changes according to the user’s input.

Custom time period with a simple input field
Custom time period with a simple input field

Selecting a date range

If the user selects a time period that requires input of a start and end date, two date pickers appear. These can be opened by clicking the calendar icon. The text in the date range input field changes according to the user’s input.

Selected time period with two date pickers (start date and end date)
Selected time period with two date pickers (start date and end date)

Styles

Validation

Use inline validation to give the user feedback, especially for errors and warnings. The possible states are “warning”, “error”, and “success”.

The dynamic date 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

See the Date Picker and Date Range Selection articles for the guidelines. They also apply to the dynamic date control.

 

List of Options

  • Only provide values that are relevant for the use case in the list of options.
  • You can also add your own values, if necessary.
  • If you use your own values, provide human readable 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

Color Picker Popover

The color picker popover consists of a color picker within a popover. You can use it to offer color selectors on toolbars (for example, triggered by a button). The color picker popover allows users to select any color.

Color picker popover
Color picker popover

Usage

Use the color picker popover if:

  • Selecting any color freely is the typical use case (for example, for user-created content).
  • There is no need for or benefit from a predefined color palette.
  • Selecting a color is needed as a toolbar action. In this case, use a button or menu button to trigger the color picker popover.

Do not use the color picker popover if:

  • You want to let users select a color directly on the page (for example, inside a form). Use the color palette instead.
  • A predefined palette is beneficial. Use a color palette popover instead.

Responsiveness

The color picker popover supports cozy and compact content densities. On a phone, the color picker popover turns into a full-screen dialog.

Size S
Size S
Size M
Size M
Size L
Size L

Layout

The color picker popover consists of a popover containing a color picker and a toolbar.

The color picker consists of the following elements:

  • The color picker box for setting lightness and saturation
  • Sliders for setting the hue and transparency (“alpha channel”)
  • Form elements for:
    • Displaying the current and new color settings (Prior to any selection, the default color is white. However, the app developer can set a different predefined color using the setSelected method.)
    • Setting the color as a hexadecimal value
    • Setting the color as red/green/blue (RGB) value (0 to 255 each)
    • Setting the color as hue/saturation/lightness (HSL) value (hue: 0 to 360 degrees, saturation: 0% to 100%, lightness: 0% to 100%)
    • Setting the transparency (“alpha channel”) value of the color (0.00 for full transparency to 1.00 for opaque)

The toolbar contains two buttons: OK (emphasized) and Cancel.

Types

The color picker popover comes in 3 flavors:

  • Simplified: The simplified color picker offers settings for hue, saturation, and lightness, but not for the alpha channel. It shows the current and new color. Text input is only possible for hex values.
'Simplified' color picker popover
'Simplified' color picker popover
  • Default: The default color picker allows all settings. It displays input fields either for red / green / blue / alpha or for hue / saturation / lightness / alpha. End users can switch between both sets of input fields.
'Default' color picker popover
'Default' color picker popover
  • Large: The large color picker allows all settings and displays all fields at the same time.
'Large' color picker popover
'Large' color picker popover

Behavior and Interaction

Colors can be selected using mouse/touch or a keyboard:

  • Mouse/touch: Users select a combination of saturation and lightness in the color picker box (click and drag). Hue and alpha values are selected with sliders.
  • Keyboard: The tab key is used to set the focus on the sliders and input fields. Values are entered using the corresponding input controls. The sliders react on arrow keys, page up / page down keys, as well as on home and end keys. The color picker box is not keyboard-enabled.

The OK button applies the new color and closes color picker popover. The Cancel button closes the color picker popover without applying the new color.

Guidelines

  • To trigger the color picker popover, use a button or a value help icon from an input field.
  • Show the selected color in another place (for example, as a color value inside the triggering input field). The color picker popover closes as soon as a color is selected.
  • Use the simplest color picker popover type that does the job.

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

Color Picker

The color picker allows users to choose any color and provides different input options for selecting colors.

Color picker
Color picker

Usage

Use the color picker if:

  • Selecting any color freely is the typical use case.

Do not use the color picker if:

  • Users need to select one color from a predefined set of colors. Use the color palette instead.
  • Selecting a color from a predefined palette is the typical case, but users should still be able to define their own colors. Use the color palette popover instead.

Responsiveness

The color picker supports cozy and compact content densities.

Size S: Color picker opens in responsive popover
Size S: Color picker opens in responsive popover
Size M – Cozy form density
Size M – Cozy form density
Size L – Compact form density
Size L – Compact form density

Layout

The color picker consists of the following elements:

  • The color picker box for setting lightness and saturation
  • Sliders for setting the hue and transparency (“alpha channel”)
  • Form elements for:
    • Displaying the current and new color settings (Prior to any selection, the default color is white. However, the app developer can set a different predefined color using the setSelected method.)
    • Setting the color as a hexadecimal value
    • Setting the color as red/green/blue (RGB) value (0 to 255 each) (optional)
    • Setting the color as hue/saturation/lightness (HSL) value (hue: 0 to 360 degrees, saturation: 0% to 100%, lightness: 0% to 100%) (optional)
    • Switching between RGB and HSL values (if applicable)
    • Setting the transparency (“alpha channel”) value of the color (0.00 for full transparency to 1.00 for opaque)
Schematic visualization of the color picker
Schematic visualization of the color picker

Types

The color picker comes in 3 flavors:

  • Simplified: The simplified color picker offers settings for hue, saturation, and lightness, but not for the alpha channel. It shows the current and new color. Text input is only possible for hex values.
'Simplified' color picker
'Simplified' color picker
  • Default: The default color picker allows all settings. It displays input fields either for red / green / blue / alpha or for hue / saturation / lightness / alpha. End users can switch between both sets of input fields.
'Default' color picker
'Default' color picker
  • Large: The large color picker allows all settings and displays all fields at the same time.
'Large' color picker
'Large' color picker

Behavior and Interaction

  • Mouse/touch: Users select a combination of saturation and lightness in the color picker box (click and drag). Hue and alpha values are selected with sliders.
  • Keyboard: The tab key is used to set the focus on the sliders and input fields. Values are entered using the corresponding input controls. The sliders react on arrow keys, page up / page down keys, as well as on home and end keys. The color picker box is not keyboard-enabled.

Guidelines

  • Do not place the color picker directly on a page. Always offer the picker in a popover or dialog.
  • Use the simplest color picker type that does the job.

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

Action Sheet

An action sheet consists of a list of options a user can select from to complete an action. Actions can be clustered if there is not enough space on the screen.

Warning
This control has a number of limitations, which were addressed with the introduction of the menu button. Use the menu button instead of the action sheet whenever possible.
Example of an action sheet popover
Example of an action sheet popover

Usage

Use the action sheet if:

  • You need an option that provides more than one action.
  • It is really important that the user stays in context on a phone.
  • You only have a small number of actions.

Do not use the action sheet if:

  • The menu provides only one option. In this case, consider using a button instead.
  • You need to show a hierarchical menu. In this case, use the menu button instead.
  • Your users would benefit more from a split button, which offers an easily-accessible default action, with the option to include additional actions.

Responsiveness

The action sheet is fully responsive. On smartphones, the actions are displayed as a list inside a dialog. On tablets and desktop devices, the actions are displayed in a popover.

Size S (Smartphone)

Action sheet dialog
Action sheet dialog

Size M (Tablet)

Action sheet popover
Action sheet popover

Size L (Desktop)

Action sheet popover
Action sheet popover

Layout

All elements in the action sheet are left-aligned. Actions are always arranged in order of importance, from top to bottom. The Cancel button uses a negative button type and is centered to differentiate it from the other app actions. The cursor/focus area for buttons within the action spans the full width of the action sheet (which in turn depends on the longest button).

Action sheet popover
Action sheet popover
Action sheet popover
Action sheet popover

Components

The following UI elements can be placed in the action sheet:

Behavior and Interaction

Clicking

A click on the overflow icon (“…”) opens either a popover or a dialog. The user can trigger an action or close the action sheet by clicking anywhere on the screen. On a smartphone, the dialog can be closed only with the Cancel button.

If the user triggers an action, the action sheet closes automatically and the system provides a message toast.

Guidelines

  • Never use only icons in the action sheet. Display text only or a combination of icon and text.
  • On smartphones, provide a Cancel button to enable the user to close the dialog without triggering an action.
  • Avoid scrolling in action sheets. If you include too many buttons in an action sheet, users have to scroll to see all the actions in the list. Not only does it take users longer to distinguish between actions, but they also find it difficult to scroll without clicking a button by mistake.
Action sheet dialog
Action sheet dialog

Resources

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

Elements and Controls

Implementation

Multi-Input Field

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

Usage

Use the multi-input field if:

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

Do not use the multi-input field if:

  • You want the user to select one entry only. In this case, use the input field or combo box instead.
  • You want the user to select from a pre-defined set of options only. In this case, use the multi-combo box instead.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

Size S

  • Cozy mode.
  • When the user clicks the multi-input field, a new full screen dialog opens. After clicking the input field and typing, the suggestions can be selected. When the user makes a selection, the dialog closes and the token is displayed.
  • The user can review the tokens by swiping them to the left or right.
Suggestions on a smartphone (size S)
Suggestions 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

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

Size L

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

Types

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

Behavior and Interaction

Adding a Token

A token can be added using suggestions or value help. As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. The user can accept the autocompleted value by pressing ENTER. The autocomplete property is set by default if suggestions are available, but can also be switched off.

When an item is selected from the suggestions dropdown, the corresponding token is created, and the input field is ready for the next entry. Tokens are placed next to each other on one line.

Warning
The typeahead input feature is not available for Android devices.
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

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

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

Multi-input field - n More (desktop)
Multi-input field - n More (desktop)
Multi-input field - n More (phone)
Multi-input field - n More (phone)

If the length of the last selected token exceeds the width of the input field, a label [n] Item/s is shown when the field is not in focus.

Clicking the [n] Item/s label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its delete icon.

If there is only one token in the input field and its length exceeds the width of the input field, the text is truncated. Clicking the token opens a popover below the input field, in which the full text of the token is shown.

Multi-input field - '1 Item' case (desktop)
Multi-input field - '1 Item' case (desktop)
Multi-input field - 'n Items' label (desktop)
Multi-input field - 'n Items' label (desktop)

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

Left/right keyboard cursor
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

Filtering

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

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

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

Multi-input field - Default filtering, autocomplete in the input field is switched off
Multi-input field - Default filtering, autocomplete in the input field is switched off

Copying and Pasting Data from a Spreadsheet or Text File

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

Grouping

You can group the items items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

Multi-input with grouped suggestions
Multi-input with grouped suggestions
Multi-input with grouped tabular suggestions
Multi-input with grouped tabular suggestions

Due to a technical limitation, the group headers are not visible when clicking on the n More text. 

Group headers not shown when clicking on n More items
Group headers not shown when clicking on n More items

Styles

The following images show how the states of the multi-input field are styled.

Unselected
Unselected
Unselected with predefined placeholder
Unselected with predefined placeholder
Unselected on hover
Unselected on hover
In focus
In focus
Selected items shown as tokens
Selected items shown as tokens
Expanded multi-selection
Expanded multi-selection
Error
Error
Warning
Warning
Success
Success
Information
Information

For details on the different states, see UI Element States.

For more information on semantic colors for value states, see How to Use Semantic Colors.

Guidelines

  • Give the control a width that is appropriate for the range of values that are going to be entered. Try to avoid setting a fixed width on this control. Instead, embed it in a proper layout (such as a form, simple form, or grid layout) and work with the layout data property.
  • Provide meaningful labels for all input fields. Do not use the placeholder as a replacement for the label. The placeholder should only provide an additional hint.
  • The multi-input field can currently contain tokens and one free text value. If you allow only validated values, display an error or warning when the user tries to leave the field to indicate that the value entered is invalid, or remove the value.
  • If users try to select an item that has been selected before, we recommend setting an error state and providing a meaningful message.
Multi-input - Error state for an item that has already been selected
Multi-input - Error state for an item that has already been selected
  • You can use the layout options of the form to add the unit of measurement (UoM) after the multi-input control. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.
Developer Hint

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

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

Properties

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

Resources

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

Elements and Controls

Implementation

Multi-Combo Box

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

Usage

Use the multi-combo box if:

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

Do not use the multi-combo box if:

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

Responsiveness

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

Size S

 Filter bar with multi-combo box - Size S
Filter bar with multi-combo box - Size S
Option list in full screen - Size S
Option list in full screen - Size S

Size M

Filter bar with multi-combo box - Size M
Filter bar with multi-combo box - Size M

Size L

Filter bar with multi-combo box - Size L
Filter bar with multi-combo box - Size L

Also see the section on behavior for mobile devices.

Components

Input Field

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

Dropdown Trigger

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

Option List

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

Components of the multi-combo box
Components of the multi-combo box

Two-Column Layout

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

Multi-combo box with a two-column layout
Multi-combo box with a two-column layout

Behavior and Interaction

Select a Value

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

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

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

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

Developer Hint
With the showitems API, you can open the option list without having the dropdown arrow in a pressed state. Clicking the arrow again opens the full option list and sets it to pressed state. This way, you can show some items on focus and all items on click.

Input Field

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

Behavior - Sizes M and L
Behavior - Sizes M and L

Choose from Option List

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

Reviewing Tokens

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

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

Multi-combo box - n More
Multi-combo box - n More

If the length of the last selected token exceeds the width of the input field, a label [n] Item/s is shown when the field is not in focus.

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

If there is only one token in the input field and its length exceeds the width of the input field, the text is truncated. Clicking the token opens a popover below the input field, in which the full text of the token is shown.

Multi-combo box - '1 Item' case (desktop)
Multi-combo box - '1 Item' case (desktop)
Multi-combo box - 'n Items' label (Desktop)
Multi-combo box - 'n Items' label (Desktop)

Filtering the Option List

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

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

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

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

Warning
The typeahead input feature is not available for Android devices.
Multi-combo box - Default filtering and auto-complete
Multi-combo box - Default filtering and auto-complete

Grouping

Option list items can be grouped. Visually, the group header is a separate line above the items it groups. It does not currently provide an interaction of its own.

Multi-combo box - Grouping (desktop)
Multi-combo box - Grouping (desktop)
Multi-combo box - Grouping (mobile, Size S)
Multi-combo box - Grouping (mobile, Size S)

Behavior for Mobile Devices

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

Clicking the Arrow

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

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

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

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

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

Input Field on Collapsed List

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

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

Multiple Selected Items

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

Swiping to display tokens
Swiping to display tokens

Copying and Pasting Data from a Spreadsheet or Text File

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

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

Styles

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

Unselected
Unselected
Unselected with predefined placeholder
Unselected with predefined placeholder
Unselected on hover
Unselected on hover
In focus
In focus
Expanded
Expanded
Hover highlighting in list
Hover highlighting in list
Expanded selection
Expanded selection
Expanded multi-selection
Expanded multi-selection
Selected items shown as tokens
Selected items shown as tokens
Error
Error
Warning
Warning
Success
Success
Information
Information

For more information on how to use the different semantic states of the control, see How to Use Semantic Colors.

Guidelines

Label

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

Placeholder

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

Option List

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

Sorting

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

  • Logical: Sort items into a meaningful order. Group related options together and show the most common options first followed by less common options.
Logical multi-combo box
Logical multi-combo box
  • Alphabetical: Sort currencies, names, and so on into alphabetical order. We recommend this for lists with more than eight items.
Alphabetical multi-combo box
Alphabetical multi-combo box
  • Numeric: Sort numeric values into a sequential order with the lowest number first.
Numeric multi-combo box
Numeric multi-combo box
  • Chronological: Sort time-related information into chronological order with the most recent first (if applicable).
Chronological multi-combo box
Chronological multi-combo box

Width

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

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

Unit of Measurement

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

Developer Hint

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

Multi-Combo Box in a Filter Scenario

The multi-combo box can serve as a filter. For example, if the multi-combo box is offered in a table toolbar, and is empty (no tokens selected), the table shows all items. If the user selects picks something in the multi-combo box, the table shows only the matching items.

In addition, users can select or deselect all items from the option list in the multi-combo box using the keyboard. This is done by focusing somewhere in the list and pressing Ctrl+A / Ctrl+Shift+A.

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

Checkbox

A checkbox lets the user set a binary value (such as “true/false”). When the user clicks the checkbox, it toggles between checked and unchecked. Checked means that the state described by the checkbox text applies, or that the item has been chosen.

The checkbox text describes the positive action (as in “true” or “yes”). The text can be either a label control to the left of the checkbox, or a checkbox text that appears to the right of the box.

  • If there is only one checkbox, you can use a label or text depending on the form format.
  • If there is more than one checkbox, the label describes the whole group of checkboxes. In this case, use the text property of the checkbox to describe the individual checkboxes.

Within a group of checkboxes, each checkbox can be checked or unchecked. The user can check multiple options.

A checkbox does not apply a setting right away; the changes take effect after user confirmation via a triggering action button (such as Save).

Enabled/disabled checkboxes
Enabled/disabled checkboxes

Usage

Use the checkbox control if:

  • Only one option can be selected or deselected, for example to accept terms of use. Use it only if the meaning is obvious (single checkbox).
  • You have a group or a list of options that can be selected independently of each other (checkbox group).
  • Your use case requires all available options to be displayed right away without any user interaction (also in read-only cases).
  • The values of the option list are primary information and need to be displayed right away.
  • Changes to the settings need to be confirmed and reviewed by the user before they are submitted. This helps prevent users from changing settings accidentally.
  • You want to group multiple suboptions under a parent option, and require an intermediate selection state (tri-state). The tri-state indicates that some (but not all) suboptions are selected.
  • The states of a switch control might be confusing for the user. For example, it’s not clear if the switch is showing a state or an action.

Do not use the checkbox control if:

  • The user needs to choose multiple options from a large list. Use a multi-combo box instead.
  • The user can choose only one option from a list. For a small list, use a radio button group instead. For a large list, use the select control or a list with multi-selection functionality.
  • You want to offer two options for a “yes/no” or “on/off” type of decision. Consider using a switch control instead.
  • The user needs to perform instantaneous actions that do not need reviewing or confirming. Consider using the switch control instead.
  • There is not enough space available on the screen. Use the combo box control instead.

Responsiveness

A checkbox can appear in two different sizes. In cozy mode, it is bigger than it is in compact mode. This makes the checkbox easier to select on touch devices. For more information on cozy and compact modes, see the article on content density.

Cozy/compact mode
Cozy/compact mode

In both sizes, the touch/click area around the checkbox is bigger than the checkbox itself, making the checkbox easier to select. Clicking inside this area toggles the checkbox.

Note: Because the touch/click area does not include the label on the left, clicking the label will not toggle the checkbox.

Checkbox click area in compact mode
Checkbox click area in compact mode
Checkbox touch/click area in cozy mode with label
Checkbox touch/click area in cozy mode with label

Layout

The checkbox control consists of a box and a text that describes the purpose of the checkbox.

If the checkbox is checked, an indicator is shown inside the box.

Although the clickable area to select/deselect a checkbox covers a wider area than the box (see the Responsiveness section), the focus is indicated by a dotted line that surrounds only the box.

If the checkbox appears alone inside a form, the text can be omitted if the label in front of the checkbox takes over its function.

Note: Because the touch/click area does not include the label on the left, clicking the label does not toggle the checkbox.

If there are several options to choose from in a form, the label describes the entire checkbox group, and the texts describe the individual checkboxes.

Since checkbox texts are also a type of label, use title case to be consistent with other labels. If the label is long, it can wrap in order to fit the text into the visible area of the content holder. There is no limit on the number of lines a text can wrap.

Exception: If one or several of the checkbox texts is very long, or is formulated as a phrase, use sentence case and appropriate ending punctuation.

For forms with labels above the fields, place the label above the checkbox group, or do not use a label. For a single checkbox, use only a checkbox text.

For forms with labels to the left of the field, place the label next to the group, aligned with the first checkbox field, or do not use a label. For a single checkbox, use only a label, or only a checkbox text.

Developer Hint
Do not use empty labels to arrange the checkboxes. Creating a label in front of each checkbox and leaving the text empty looks fine – nobody sees the label, and the checkboxes are aligned correctly underneath each other. However, the screen reader will notice these labels and read each of them as “label”. Instead, use the layout data property (layoutData) for the checkbox. In this property, force a line break (linebreak) and set the value of the indents in sizes L and M (indentL, indentM) according to the value of the label span in the simple form (labelSpanL, labelSpanM).
Checkbox layout
Checkbox layout
Short checkbox text in title case; Long checkbox text in sentence case
Short checkbox text in title case; Long checkbox text in sentence case
Checkbox text wrap
Checkbox text wrap
Checkbox group with label on top or to the left
Checkbox group with label on top or to the left
Checkbox group without label
Checkbox group without label
Single checkbox with label or with text
Single checkbox with label or with text

Behavior and Interaction

Clicking a checkbox toggles the state of the checkbox between checked and unchecked.

Tri-State

The main purpose of this state is to represent the mixed selection states of dependent input fields. If some (but not all) of the dependent fields are selected, the checkbox shows a partially selected state. This is only a visual state and can’t be achieved by a direct user interaction.

Checkbox interaction states
Checkbox interaction states

Properties

You can set the width of the element containing the checkbox and the text manually (property: width).

If the text exceeds the available width, it can wrap. The touchable area for toggling the checkbox ends where the text ends.

If the width allows more space than the text requires, white space is added. The touchable area for toggling the checkbox is increased according to the manually-set width.

The text can be positioned manually in this space (property: textAlign). However, we do not recommend using the right-align option, which can result in a large amount of white space between the checkbox and the checkbox text.

If a checkbox is part of an editable form, it can be edited in when the form is in edit mode. In display mode, the checkbox uses its “display only” state (property: displayOnly).

If the checkbox appears in a read-only form, set the checkbox to read-only (property editable = “false”).

Do not combine the settings “disabled” and “read-only”. This is technically possible, but does not make any sense.

The checkbox can represent a mixed selection state, or tri-state (property: partiallySelected). The visual state depends on the value of the selected property.

Don't
Checkbox text - Incorrect positioning
Checkbox text - Incorrect positioning
Checkbox interaction states
Checkbox interaction states

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 (also know as ALV) can 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).
  • Touch interaction: The user 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

In rare cases, show the actions within the line item. One example would be an Add to Cart button in a shopping application. 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. Provide a separate column per action. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

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 – Leaf node
Tree table – Leaf node

Cell

Each cell provides one data point. It can contain one of the following controls to display the 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).

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 uses “lazy loading”.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.TreeTable, property: rowHeight).

The tree table is optimized to allow faster scrolling within the first 1000 items.

Tree table – Vertical scroll bar
Tree table – Vertical scroll bar

Behavior and Interaction

Selection

The tree provides the following possibilities:

No selection: Items cannot be selected. (property: selectionMode = None)

Tree table – No selection
Tree table – No selection

Single selection: One item in the tree table can be selected. A row selector column is shown. (property: selectionMode = Single)

Tree table – Single selection
Tree table – Single selection

Multiple selection: One or more items can be selected. The tree 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. The Shift key can be used to select a range.

For multiple selection, you can choose between two variants.

  • Multi-toggle mode (property: selectionMode = MultiToggle)
  • Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)

These variants behave differently when the user selects more items than are currently loaded in the front end.

Multi-toggle

In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end. All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

Multi-selection plug-in

If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:

  • By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
  • You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
    • The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and a message can appear (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
    • If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets.
  • If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.
Information
When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

  • The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
  • The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.TreeTable, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

Tree table – Multiple selection
Tree table – Multiple selection
Using the multi-selection plug-in with a limit
Using the multi-selection plug-in with a limit

Selection Behavior

An item can be selected in different ways, depending on the configuration of the tree table (sap.ui.table.Table, property: selectionBehavior):

  • Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection tree tables if clicking a row or a cell is not used for anything else.
  • RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
  • RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection tree tables if clicking a row or a cell is not used for another purpose, such as navigation.

Set the property collapseRecursive to “false” in order to keep the selection on subnodes even after collapsing and expanding the root node.

Drag and Drop

One or several items can be repositioned within a table or moved to other UI elements using drag and drop operations (sap.ui.table.TreeTable, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position  (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and Drop
Drag and Drop

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.

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows (like group headers). Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or SHIFT+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Tree table with context menu
Tree table with context menu

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

What exactly needs to stay or be removed is highly dependent on the kind of structure and data your tree table displays. For many trees, the following approach works well if you want to apply filters only to the leaves of a tree:

  • Remove all leaves that don’t fit the filter criteria
  • Remove empty nodes

Where nodes need to be filtered, keep the following in mind:

  • A node may or may not fit the filter criteria.
  • A node can contain items (nodes and/or leaves) that fit the filter criteria.

Because of this, the results might contain more nodes than those that are relevant for the filter criteria.

Developer Hint
The tree table itself has no influence on the filter result. It sends a filter request and displays whatever comes back. Make sure that the result set is meaningful.

Sorting

First of all: Is sorting meaningful in your tree? If so, decide on a meaningful default sort order.

If sorting is meaningful, is it meaningful on all levels? Or does the tree structure need to be stable? In the latter case, sort only leaves, but not nodes.

To display the current sort state, an icon is shown in the column header of the most recently sorted column. This icon indicates the sort direction (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

The descending sort order must always be the exact reverse of the ascending sort order. For each column, provide a meaningful sort order. For example:

  • Sort text alphabetically
  • Sort numbers by their value
  • Sort status information by the severity of the status:
    • Ascending: Sort status information from positive to negative, with neutral last.
    • Descending: Sort status information from negative to positive, with neutral first.
    • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
    • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

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.

Selection

  • We strongly recommend using the multi-selection plug-in. This ensures that all items selected using Select All or as part of a range are included – even if some items were not initially loaded in the front end. This is not the case if you use the multi-toggle option.
  • Do not limit the range selection for the multi-selection plug-in unless you have to.
    • If the dataset is small and/or completely available in the front-end, set the limit property to 0 to enable the Select All option and allow users to select any range.
    • If you have a large dataset, set a limit on the number of selected items to avoid performance issues. Also bear in mind that some actions won’t be helpful if the dataset is too big (for example, a delete operation on 2 million database entries).
  • When setting a limit, also display the corresponding message when the user selects more items at once than the limit allows (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification).
  • In multiple selection mode, do not show checkboxes in the first data column in the default delivery to avoid confusion.

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

For adding items, place an Add or Create text button on the table toolbar.

  • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
  • Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the tree table or node:

  • If nothing is selected, add the new item to the root.
  • If a single node is selected, add the new item to the selected node.
  • If a single leaf is selected, add the new item as child of this leaf. The original selected item becomes a node.

If your tree doesn’t support adding items to the root, selected node, or selected leaf, disable Create or Add for the corresponding levels.

Disable Create or Add if more than one item is selected.

For more details, see the guidelines for managing objects (including subarticles).

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Let the user choose whether to apply the action anyway or cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element – States.

If the action was applied and the items are still available, keep them selected.

Message for an action that applies to a part of a selection
Message for an action that applies to a part of a selection

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.
  • Icons are centered.
  • Micro charts are left-aligned.

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 correct format for the user’s language/country.
  • If you show both a a text and an ID, consider the requirements for sorting, grouping and filtering:
    • If users need to sort, group, and/or filter by both text and ID, show the text and ID in two separate columns.
    • If users only need to sort, group, and/or filter by either text or ID, show the ID in parentheses after the corresponding text.
  • If the unit of measurement is the same for all rows, show the unit of measurement in the column header. Otherwise, show the unit of measurement within the row.
  • If you want to let users sort, filter, or group by amount and by unit of measure independently, put both in different columns. If you combine them in one column, offer only sorting, filtering, and grouping by amount.

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.

Navigation

To trigger navigation on line item level, choose one of the following options:

  • Use a link for the attribute that identifies the row. Clicking the link triggers the navigation. This is the preferred option.
  • Add the RowActions column and show the navigation arrow (  ) at the end of the row. No column header text is required. The navigation column is fixed and will not scroll away. Users also cannot personalize this column. The navigation arrow triggers the navigation.
    Do not use the RowActions column for actions other than navigation and deletion.

Special case: Multi-selection in a master-detail scenario
When a multi-selection table is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case, you can display a “navigated” indicator to show which item is currently open.

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.
  • Do not wrap content, truncate it. End users can easily change the column width to see the full text.
Don't
Avoid: The initial visible content should not be truncated in the default delivery
Avoid: The initial visible content should not be truncated in the default delivery
Don't
Never wrap texts
Never wrap texts
  • 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
  • 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.
  • Set the property collapseRecursive to “false” in order to keep the selection on subnodes even after collapsing and expanding the root node.

Empty Tree Tables

Avoid empty tree tables. If necessary, provide instructions on how to fill the tree table with data (sap.ui.table.TreeTable, properties: noDataText, showNoData).

Examples:

  • If a tree table is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the tree table with data.
  • If a tree table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    No filters set. To start, enter your search and filter settings and run the search.
  • If a tree table is used together with a filter bar and the filter does not return results, use the following text:
    No items found. Check the search and filter settings.

Adapt the texts above if:

  • The standard text is not precise enough for your use case (for example, no search is offered, only the search is offered).
  • You are using the live search (no Go button in the filter bar). In this case, leave out “run the search”.
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).

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

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.ui.table.TreeTable, aggregation: rowSettingsTemplate)

Highlighted items
Highlighted items

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. Also, because there is no generic keyboard interaction, drag and drop isn’t accessible. Moreover, drag and drop is not available on all browsers. For these reasons, offer drag and drop only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.

Use drag and drop only in addition to existing visible UI elements
Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within a tree table, use the following options:

  • For dropping items as a child, use whole nodes as drop targets (sap.ui.core.dnd.DropPosition.On).
  • For dropping items on the same level, use the space between items as drop targets (sap.ui.core.dnd.DropPosition.Between).
  • If you want to allow users to drop items as a child or sibling, offer both drop targets (sap.ui.core.dnd.DropPosition.OnOrBetween).

This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop target on an Item
Drop target on an Item

Do not combine rearranging items within one level and sorting. If you really need to do so, make sure there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

Moving items from one node to another can be combined with sorting without any issues.

Don't
Do not combine rearranging items on the same level with sorting
Do not combine rearranging items on the same level with sorting

Visible Alternatives to Drag and Drop

Depending on the functionality you need, use one or more of the following alternatives:

  • To move items up or down within a node:
    Use the  Move Up and  Move Down buttons on the toolbar. These buttons move the selected items until the first selected item can’t be moved up / the last selected item can’t be moved down any further.
    Depending on your tree, this can make sense for both leaves and nodes, only for leaves, or only for nodes. When moving a node, move the whole node and (if applicable) all its children up or down to the next position within the parent node.
    Always make sure that when the user moves an item in one direction and then moves it back, the order is the same as it was before.
    Do not combine the option to move items up and down with sorting.
  • To move items to another node:
    Use Copy and Paste buttons on the toolbar.
    Alternatively, offer a Move To button. Clicking Move To opens a dialog that shows all the nodes of the tree, but no leaves. Selecting an item in this dialog closes the dialog and moves the corresponding items to the selected node.
  • To change the level of an item:
    In some trees, such as document structures, users can change the level of an item without affecting the level of parent or child items. In this case, use left and right arrow buttons (   ).

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar). Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

The context menu can be triggered for the table, row, or cell. However, we do not recommend using context menus for cells: because the content of a cell is a different touch target than the cell itself, opening a cell context menu via touch is quite hard, even in cozy mode.

Do not combine context menus with condensed mode: editable controls fill the entire space inside a cell. Because of this, context menus cannot be opened at all with touch or mouse interaction.

Tables in Object Pages

In the object page, we advise against using analytical, grid, and tree tables. Instead, use a responsive table and offer navigation to a list report with the table types mentioned above.

For more information on the use of tables within the object page, see the Tables section of the Object Page article.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting table data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button
'Export to Spreadsheet' menu button

Resources

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

Elements and Controls

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 for a master-detail scenario using the flexible column layout and in popovers or dialogs. In certain use cases, they can also be used in the dynamic page layout.

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 first column of the flexible column layout).
  • Selecting one or more items out of a set of hierarchically structured items is a main use case.
  • The hierarchy has a restricted number of levels (up to about 12, depending on the content) 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 very 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 around 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 wrap to ensure that the tree adapts to the new size.

In addition, the tree changes the indentation per level dynamically when the user expands a node, based on number of levels currently showing.

Tree displaying 2 levels
Tree displaying 2 levels
Tree displaying 3 levels
Tree displaying 3 levels
Tree displaying 4 levels
Tree displaying 4 levels

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)
  • text
  • A counter (optional)
  • Additional buttons with actions such as Edit, Navigate, or Delete (optional)

If additional controls are needed, use a custom tree item. The custom tree item allows you to use any combination of controls inside the tree.

Standard tree item
Standard tree item

Behavior and Interaction (incl. Gestures)

Tree Level

Scrolling

The height of the tree is defined by the number of items it contains. It does not have its own scroll container, but is scrolled together with the app.

Same tree, with different expand state
Same tree, with different expand state

When the user scrolls, the title and the filter infobar can stick to the top of the surrounding layout container (sap.m.Tree, property: sticky).

Information
The “sticky” feature comes with some limitations:

  • It is not available on all browsers. In non-supporting browsers, the corresponding areas are not fixed on top of the surrounding layout container while scrolling.
  • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the table is placed within the object page.
  • If focus is set to a sticky area, the tree is automatically scrolled to top.

Sticky title
Sticky title

Selection Modes

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.

Multiple selection: 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 of the others. The Shift key can be used to select a range (sap.m.ListMode.MultiSelect).

Developer Hint
In multiple selection mode, users can (de)select all items using the shortcut CTRL+A. This only affects items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded (for example, items added via lazy loading with growingScrollToLoad). This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

Also note that CTRL+A only (de)selects items within expanded nodes.

To process all items, listen to the selectionChange event and to its flag selectAll. This indicates whether CTRL+A was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

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

Line Item Level

Expandable and Collapsible Nodes

An Expand/Collapse button is provided automatically for each node.

Expand/collapse button
Expand/collapse button

Highlight an Item

To highlight an item, use the “highlight” indicator (sap.m.TreeItemBase, properties: highlight).

Highlighted item
Highlighted item

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 the line triggers the navigation event. However, clicking 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

Indicate Navigated Item

When multi-selection is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case only (multi-selection tree with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.TreeItemBase, property: navigated).

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

Context Menu

You can attach a context menu (sap.m.Menu) to a tree. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

The context menu can be triggered for the tree or per item.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or SHIFT+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a tree is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Tree - context menu
Tree - context menu

Drag and Drop

One or several items can be repositioned within a tree or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop
Whole item as drop target
Whole item as drop target

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.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the tree. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning
The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

  • The number of rows in the table
  • The number of displayed columns
  • The complexity of the cell content (for example, simple text vs. complex charts)
  • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
  • The browser being used

Title

Use a title only if the title of the tree is not indicated in the surrounding area. If needed, implement the title text by adding a title to a toolbar. Place the toolbar above the tree.

Do not use a title if it simply repeats text that is already above the tree. For example:

  • Beverages tree is the only control on a tab labeled Beverages.
  • A section or subsection on an object page contains only one tree.

Use a title if you need the item count, toolbar, or variant management. To avoid repeating text, feel free to use generic text as a title, such as Items.
Exception: If the surrounding area contains the title, and both the item count and toolbar can be added to the surrounding area, no additional title is needed.
Example: An object page (sub-)section contains only one tree. In this case, add the item count and the table toolbar to the (sub-)section header.

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 only leaves (for example, if nodes are mainly used for categorization).

Remove the item count in the title if there are zero items.

If possible, keep the toolbar sticky (sap.m.Tree, property: sticky).

Developer Hint
Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the tree.

If you don’t use a title (for example, to avoid repetition), make sure that the tree is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

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

 

Examples:

  • If a tree is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the tree with data.
  • If a tree is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    No filters set. To start, enter your search and filter settings and run the search.
  • If a tree is used together with a filter bar and the filter does not return results, use the following text:
    No items found. Check the search and filter settings.

Adapt the texts above if:

  • The text is not precise enough for your use case (for example, no search is offered, only the search is offered).
  • You are using the live search (no Go button in the filter bar). In this case, leave out “run the search”.
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).
Provide meaningful instructions within an empty tree
Provide meaningful instructions within an empty tree

Highlighting Items

To show that an item needs attention, you can display a highlight indicator in front of the item. The highlight indicator can be used to indicate:

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors.

(sap.m.ListItemBase, 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 contains an error, for example within the global edit flow, add the string (Contains errors) to the text of the item and highlight the row accordingly.

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: AddCollapse AllExpand 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.

Add Items

For adding items, place an Add or Create text button on the toolbar.

  • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
  • Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the tree or node:

  • If nothing is selected, add the new item to the root.
  • If a single node is selected, add the new item to the selected node.
  • If a single leaf is selected, add the new item as a child of this leaf. The original selected item becomes a node.

If your tree doesn’t support adding items to the root, selected node, or selected leaf, disable Create or Add for the corresponding levels.

Disable Create or Add if more than one item is selected.

For more details, see guidelines for managing objects (including subarticles).

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that tells the user how many items will be affected. Let users choose whether to apply the action anyway or cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element – States.

If the action was applied and the items are still available, keep them selected.

Message for an action that applies to a part of a selection
Message for an action that applies to a part of a selection

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.

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. Also, because there is no generic keyboard interaction, drag and drop isn’t accessible. Moreover, drag and drop is not available on all browsers. For these reasons, offer drag and drop only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.

Use drag and drop only in addition to existing visible UI elements
Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within a tree, use the following options:

  • For dropping items as a child, use whole nodes as drop targets (sap.ui.core.dnd.DropPosition.On).
  • For dropping items on the same level, use the space between items as drop targets (sap.ui.core.dnd.DropPosition.Between).
  • If you want to allow users to drop items as a child or sibling, offer both drop targets (sap.ui.core.dnd.DropPosition.OnOrBetween).

This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Do not combine rearranging items within one level and sorting. If you really need to do so, make sure there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

Moving items from one node to another can be combined with sorting without any issues.

Drop targets in between items
Drop targets in between items

Visible Alternatives to Drag and Drop

Depending on the functionality you need, use one or more of the following alternatives:

  • To move items up or down within a node:
    Use the  Move Up and  Move Down buttons on the toolbar. These buttons move the selected items until the first selected item can’t be moved up or the last selected item can’t be moved down any further.
    Depending on your tree, this can make sense for both leaves and nodes, only for leaves, or only for nodes. When moving a node, move the whole node and (if applicable) all its children up or down to the next position within the parent node.
    Always make sure that when the user moves an item in one direction and then moves it back, the order is the same as it was before.
    Do not combine the option to move items up and down with sorting.
  • To move items to another node:
    Use Copy and Paste buttons on the toolbar.
    Alternatively, offer a Move To button. Clicking Move To opens a dialog that shows all the nodes of the tree, but no leaves. Selecting an item in this dialog closes the dialog and moves the corresponding items to the selected node.
  • To change the level of an item:
    In some trees, such as document structures, users can change the level of an item without affecting the level of parent or child items. In this case, use left and right arrow buttons (   ).

Filtering

What exactly needs to stay or be removed is highly dependent on the kind of structure and data your tree displays. For many trees, the following approach works well if you want to apply filters only to the leaves of a tree:

  • Remove all leaves that don’t fit the filter criteria
  • Remove empty nodes

If you also apply filters to nodes, keep the following in mind:

  • A node may or may not fit the filter criteria.
  • A node can contain items (nodes and/or leaves) that fit the filter criteria.

Because of this, the results might contain more nodes than those that are relevant for the filter criteria.

Developer Hint
The tree control itself has no influence on the filter result. It sends a filter request and displays whatever comes back. Make sure that the result set is meaningful.
[/vc_row_inner]

Sorting

Before you start, ask yourself if sorting is meaningful in your tree. If so, decide on a meaningful default sort order.

If sorting is meaningful, is it meaningful on all levels? Or does the tree structure need to be stable? In the latter case, sort only leaves, but not nodes.

The descending sort order must always be the exact reverse of the ascending sort order. Use a meaningful sort order. For example:

  • Sort text alphabetically
  • Sort numbers by their value
  • Sort status information by the severity of the status:
    • Ascending: Sort status information from positive to negative, with neutral last.
    • Descending: Sort status information from negative to positive, with neutral first.
    • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
    • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting the tree data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button
'Export to Spreadsheet' menu button

Resources

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

Elements and Controls

Implementation

Table Toolbar

The table toolbar always appears above the table. The control is used for key actions that impact the entire table.

Usage

Use the table toolbar if:

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

Do not use the table toolbar if:

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

Responsiveness

To enable responsiveness, use the overflow toolbar control. For more information, see Toolbar Overview – Responsiveness.

Components

The table toolbar can contain several components, including a title and several types of button. Actions are grouped by the following action types:

  • Finalizing actions, such as Save or Cancel. Finalizing actions are app-specific and are used only if the table is editable.
  • Business actions, such as Edit or Create. Business actions can be app-specific or general object management actions.
  • Actions for managing the content, such as Sort or Filter. These settings are also known as “view settings”.
  • Generic actions, such as Export to Spreadsheet.

Between the groups, add a separator line.

The following content can be part of the table toolbar. Use only the content your users really need. For the remaining content, keep the order shown below:

  • Title
  • Variant management or content switch (for example, as used to switch between multiple views in a list report)
  • Search
  • Finalizing actions:
    • Save
    • Cancel
  • Business actions: Use this action type for app-specific actions. This group contains:
    • App-specific business actions
    • Actions for object management
      • Create (for new items) or Add (for existing items)
      • Edit
      • Delete (if the object itself is deleted) or Remove (if the reference to an item is removed)
    • Paste

The order of actions in this group is not “fixed”. Place the most important action first, followed by the second most important action, an so on. Try to keep Create/Add, Edit, and Delete/Remove together, but only if this is meaningful in your app.
Exception: Keep Paste as the last action in this category.

All mentioned components in the correct order
All mentioned components in the correct order

Behavior and Interaction

App-Specific Business Actions

If needed, you can define your own actions for the app. In this case, use text-only buttons with a short, unambiguous text for the action the button performs. A button text is usually a single-word verb (for example, Share). Note that text strings can be longer in other languages.

Table toolbar with app-specific buttons
Table toolbar with app-specific buttons

Title

A title provides a short, meaningful summary of the content, mostly in a single word. To display a title, use the title control.

In addition, the title can be followed by an item counter (the number of items in brackets).

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

Title with item counter in the table toolbar
Title with item counter in the table toolbar

Variant Management

In tables, a variant stores all the settings that define the table view, such as the column layout, column visibility, sorting, filter settings, and grouping. The variant management control enables users to load, save, and change variants. In most cases, variant management replaces the title.

Variant management in the table toolbar
Variant management in the table toolbar

Title and Variant Management

If you need both a title and variant management, place the variant management control directly after the title. Use a separator between the title and variant management.

Since using both controls often leads to truncation problems, this pattern is not recommended.

Title with variant management
Title with variant management

Content Switch

To switch between different predefined views, use a select control or a segmented button. The content switch replaces the title and the variant management control. In the rare case that the content switch is shown together with a title, the content switch follows the title.

A predefined view contains settings for sorting, filtering, grouping, column layout, and column visibility. Nevertheless, in most cases, the content switch is just used for different filter settings like All, Mine, and Others. In this case, make sure that the content switch doesn’t interfere with other filter settings. For example, remove the corresponding filter from the filter bar. If possible, include an item counter per view.

Another common pattern for content switches are views like By X, and By Y, which are usually defined using group settings.

Use the segmented button and the select control as follows:

  • For a limited set of views (2-3), use the segmented button for desktop and tablet devices. Replace it with a select control if there is not enough screen space.
  • If the number of views can change or is larger than 3, use the select control.

For more information, see multiple views for list reports.

Segmented button with a counter
Segmented button with a counter
Segmented text button to switch content
Segmented text button to switch content
Select control to switch content
Select control to switch content

Search

For tables with a large number of items, consider adding a search field. Use a search field only if there is no other way to search within the table (for example, if there is no additional filter bar).

Place the search field on the right side of the toolbar. Since the search field cannot be moved into the overflow menu, always provide a minimum width.

Ideally, search for results in all columns. As a minimum, search in all currently visible columns.

For more information, see Search.

Search in the table toolbar
Search in the table toolbar

Edit

There are several options for editing a table:

Edit a Single Item

To allow the user to edit a single item, show an icon-only Edit button at the end of the item (depending on the table control, use sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive; or row actions). The user can click the button to trigger the edit event. Use this event to make the item editable.

Editing a single item
Editing a single item

Mass Editing

See: Mass Editing

Edit the Whole Table

To let the user edit a whole table, use a text-only Edit button. When the user triggers the edit action, switch the table to edit mode. In edit mode, do not show the Edit button and add the finalizing actions Save and Cancel instead. Remove any actions that are meaningless in edit mode. Keep the view settings available.

See also: Manage Objects.

 Table in display mode with 'Edit' as the most important action
Table in display mode with 'Edit' as the most important action
Table in edit mode
Table in edit mode

Create / Add

Use a text button for Create or Add actions. If the Create or Add action is a main function, never move it into the overflow.

See also: Manage Objects.

Table toolbar with 'Create' button
Table toolbar with 'Create' button
Table toolbar with 'Add' button
Table toolbar with 'Add' button

Delete / Remove

Use a text button for Delete or Remove actions. In most cases, Delete is used together with Create, while Remove is used together with Add.

If the Delete or Remove action is a main function, never move it into the overflow.

See also: Manage Objects

Table toolbar with 'Delete' button
Table toolbar with 'Delete' button
Table toolbar with 'Remove' button
Table toolbar with 'Remove' button

Sort, Filter, Group

When the user chooses one of these actions, open the view settings dialog or the P13n Dialog with only the corresponding settings.

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

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

Ensure a consistent user experience. When a user reopens the app and if variant management is not used, show the table with the same view settings that were last defined by this user.

For more information, see Table Personalization.

Triggers for the different view settings (sort, filter, and group)
Triggers for the different view settings (sort, filter, and group)

Column Settings

Use the table personalization dialog or the P13n Dialog for adding, removing, and rearranging columns.

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

Ensure a consistent user experience. When a user reopens the app and if variant management is not used, show the table with the same column settings that were last defined by this user.

For more information, see Table Personalization.

Table toolbar with 'Column Settings' button
Table toolbar with 'Column Settings' button

Export to Spreadsheet

The Export to Spreadsheet action allows the user to export table rows and is represented by an icon-only menu button.

Table toolbar with the 'Export to Spreadsheet' menu button
Table toolbar with the 'Export to Spreadsheet' menu button

Print

The action for printing table items is represented by an icon-only button.

Table toolbar with 'Print' button
Table toolbar with 'Print' button

View Switch

View switches are right-aligned in the toolbar and allow the user to switch between different chart types and different controls for displaying items (for example list, responsive table, grid list). Provide the view switch if a chart relies on subtle color differences or gradients of color. In these cases, users with visual impairments can switch to the table view.

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

Define the number of chart types and switches with care. Offer only chart types that are meaningful for visualizing the respective data and that best assist the user. Ideally, offer no more than three types of visualization.

The sequence of chart type switches is not fixed. Sort them in order of importance.

The chart type currently in use is highlighted. To show this, use a segmented button with icons.

For more information about the icons and the chart types they represent, see Chart Toolbar.

Styles

On the table toolbar, use the following button styles:

  • If the single primary action for the whole page is on the table toolbar, use the emphasized button style.
  • if the single primary action for the whole page is not on the table toolbar, you can still highlight the most important button of the table toolbar by using the ghost button style.
  • For secondary actions and negative path actions, use the transparent button style.
  • For split buttons and menu buttons, use the transparent button style.
  • Do not use semantic button styles on the table toolbar.

For more information, see Button and Action Placement.

Guidelines

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Let the user choose whether to apply the action anyway or cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element States.

Message for an action that applies to a part of a selection
Message for an action that applies to a part of a selection

If the items are still available after the action was applied, keep them selected.

For further guidelines, see Toolbar Overview – Guidelines.

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

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 tableform 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. By contrast, the analytical table supports only a very limited set of controls.
  • The focus is 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 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 expect the table to contain more than around 1,000 rows. Try using the analytical table or grid table instead; they are easier to handle, perform better, and are 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 be more appropriate because each cell contains only one data point. By contrast, the responsive table offers greater flexibility within line items, including the ability to add more data points per cell and 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 child nodes. 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 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
Do not use a responsive table as a form
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 responsive table is optimized for viewing one line item at a time with no scrolling 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 for the corresponding cell is provided as a label/value pair. The label is defined by the column header, and the value is taken from the corresponding cell. Labels can be displayed next to the value or above the value.

Within the pop-in area, the label/value pairs can be displayed in the following ways (sap.m.Table, property: PopinLayout):

  • Block: Label/value pairs are listed one below the other.
  • GridSmall: Label/value pairs are displayed next to each other in equally spaced grid cells. An additional column is shown for each 13 rem of available width (208 px with default browser settings). If the number of grid cells exceeds the available width, the grid cells wrap. On S size, this layout transforms automatically to a block layout.
  • GridLarge: The display logic is the same as for GridSmall,, but grid columns come with a larger minimum width (26 rem instead of 13 rem).

In all layouts, you can show the labels next to or above (recommended) the corresponding data.

The responsive table uses all the available space, and does not provide any padding. If there is space around the table, it comes from the spacing defined for the surrounding layout container.

Information
The GridSmall and GridLarge layouts are not available in all browsers. If the chosen layout is not available, it is automatically changed to Block layout.
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)

The responsive behavior is optional. If it is not used, the responsive table just minimizes all visible columns until they are no longer readable.

There are two ways to configure responsiveness: auto pop-in mode and manual pop-in mode (sap.m.Table, property: autoPopinMode).

The auto pop-in mode ensures responsiveness automatically and is sufficient in most cases. You can still influence the behavior per column, but only to a limited extent.

The manual mode is more flexible, but needs are more configuration. This configuration becomes more cumbersome when table columns can be shown/hidden or re-ordered. On the other hand, only the manual mode allows you to:

  • Let more than one column stay in the tabular layout
  • Move more than one column into the pop-in area at once
  • Hide columns instead of moving them to the pop-in area

In both modes, the responsive table ensures that at least one column always remains in the table layout.

Auto Pop-In Mode

The auto pop-in mode handles responsiveness automatically. You can optimize this to a certain extent by adapting the behavior per column.

Columns have a minimum width. As soon as the width of all the visible columns exceeds the table width, the right-most column moves to the pop-in. The default minimum width per column is 8 rem. You can change this value for each column (sap.m.Column, property: autoPopinWidth). To further influence the behavior, you can assign columns a priority. Low-priority columns move to the pop-in first (right-most low priority column first), medium-priority columns next, and high-priority columns last. The default priority is “none” which is handled like the “medium” priority (sap.m.Column, property: importance). In auto pop-in mode, all other pop-in-related column settings are ignored.

Manual Pop-In Mode

The manual pop-in mode allows more flexibility but also requires more effort if you want it to work in a meaningful way. You also need to invest additional effort if table columns can be shown/hidden or re-ordered.

You need to configure each column manually. Depending on the width of the table (in pixels), the column needs to know which of the following responses is required:

  • Stay in the table layout (in auto pop-in mode, only one column stays in the table layout).
  • Move to the pop-in (sap.m.Column, with the properties: demandPopin, minScreenWidth, popinHAlign, popinDisplay).
  • Hide (not possible in auto pop-in mode)

By default, the table width is assumed to be the screen width. If the table does not use the full width of the screen, app developers must configure the table accordingly (sap.m.Table, property: contextualWidth).

Because you configure the pop-in response for each column individually, you can also handle more than one column at a given breakpoint. This allows you to move several columns to the pop-in area at once, which isn’t possible in auto pop-in mode

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

Example for Block Layout

A typical responsive table.

A typical responsive table
A typical responsive table

Hide the information column for a width smaller than 570 px.

Hiding the information column
Hiding the information column

Move the column “vendor” to the pop-in area for a 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 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 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 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

Example for GridLarge Layout

A more complex responsive table.

A more complex responsive table (full screen without pop-in)
A more complex responsive table (full screen without pop-in)

In this example, the Average Occupancy Rate and Available In columns move to the pop-in area if the screen width is less than 1900 pixels.

GridLarge layout - 'Average Occupancy Rate' and 'Available In' columns move to the pop-in area
GridLarge layout - 'Average Occupancy Rate' and 'Available In' columns move to the pop-in area

If the width is less than 1500 pixels, the Average Stay column moves to the pop-in area.

GridLarge layout - 'Average Stay' column moves to the pop-in area
GridLarge layout - 'Average Stay' column moves to the pop-in area

If the width is less than 1100 pixels, the Description column moves to the pop-in area. Since all four columns in the pop-in area do not fit into one row, the pop-in wraps.

GridLarge layout - 'Description' column moves to the pop-in area
GridLarge layout - 'Description' column moves to the pop-in area

If the width is reduced even further, the Details column moves to the pop-in area. On this narrow screen, only one column fits into one pop-in row, so it looks exactly like the block layout.

GridLarge layout - 'Details' column moves to the pop-in area
GridLarge layout - 'Details' column moves to the pop-in area

Layout

The optional title bar consists of the title of the responsive table, an item counter, variant management, and the toolbar.

The filter info bar appears when the responsive table is filtered, and 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 contains the title of the responsive table, an item counter, 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 AddEdit, 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 within 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, see object display components.
You can use the table footer to display additional static information relating to the table content.
The More button loads more items to the front end if not all items have yet been loaded.
Components of the responsive table
Components of the responsive table

Behavior and Interaction

The responsive table is quite flexible with regard to its content.

Table Level

Scroll

The height of the table is defined by the number 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 triggered by scrolling (preferred), or by clicking the More button.

Same table, different number of items
Same table, different number of items

When the user scrolls, the title bar, column headers, and filter info bar can stick to the top of the surrounding layout container (sap.m.Table, property: sticky).

Information
The “sticky” feature comes with some limitations:

  • It is not available on all browsers. In non-supporting browsers, the corresponding areas (title bar, column headers, filter info bar) are not fixed on top of the surrounding layout container while scrolling.
  • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the table is placed within the object page.
  • If focus is set to a fixed column header, the table is automatically scrolled to top.

Sticky table title and sticky column header
Sticky table title and sticky column header

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.
  • If the corresponding column can contain blank cells. Otherwise, it is cumbersome to differentiate between blank values and merged values.
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 modes (sap.m.Table/ sap.m.ListBase, property: mode):

  • None: Items cannot be selected (sap.m.ListMode.None).
    Beware: Line items can still use the sap.m.ListType “navigation”, which allows click handling on specific line items. Only use this option if the click triggers navigation to a corresponding line item details page.
  • Single selection master: One item in the responsive table can be selected. Items are selected by clicking or tapping the whole row. The single select master mode has no obvious visual cues, such as checkboxes or radio buttons. It only provides a light blue background for the selected state. Because of this, it can barely be differentiated from tables without selection (mode: None). Single select master is the preferred mode for single selection (sap.m.ListMode.SingleSelectMaster).
  • Single selection left: One item in the responsive table can be selected. For this, the responsive table provides radio buttons on the left side of each line item. Only use this mode if row clicks are being used for something else, such as navigation. (sap.m.ListMode.SingleSelectLeft).
  • Multiple selection: Users can select one or more items using the checkboxes on the left side of each line item. The Shift key can be used to select a range. Users can (de)select all items using the Select All checkbox to the left of the column header. Select All should (de)select all items that the user can reach by scrolling.  (sap.m.ListMode.MultiSelect).
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.
SIngle selection left, with radio buttons. Use only if row clicks are used for something else.
Multiple selection
Multiple selection

Group

For grouping items, a group header is displayed (sap.m.GroupHeaderListItem). 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 items already loaded 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 in growing mode. 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 'delete' mode
Responsive table in 'delete' mode

Highlight an Item

To highlight an item, use the “highlight” indicator (sap.m.ColumnListItem, properties: highlight).

Highlighted item
Highlighted item

Navigate

To allow navigation from a line item, use an item with the type “navigation” (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This creates an indicator at the end of the line (“>”) and the entire line item becomes clickable. If the user clicks or taps on the line, 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.

By contrast, clicking an interactive control within a line item does not trigger the navigation event. Instead, the corresponding control handles the click event.

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

Indicate Navigated Item

When multi-selection is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case only (multi-selection table with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.ColumnListItem, property: navigated).

Navigated item
Navigated item

Edit Line Items

To allow editing for a line item, 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, for example, 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

Drag and Drop

One or several items can be repositioned within a table or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop
Whole item as drop target
Whole item as drop target

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column). Context menus can be implemented for a specific table or row.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or SHIFT+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Responsive table with a context menu
Responsive table with a context menu

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

Alongside textual elements, you can also add any control to a table cell, such as input fields, microcharts, buttons, and so on.

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.

With the View Settings dialog, users can sort, filter, and group by each of these data points.

Several controls per cell
Several controls per cell

You can also have different controls in different rows in the same column. This could be the case if one item is locked, but another item is in edit mode, for example.

Different controls per column
Different controls per column

Guidelines

Responsiveness

In most cases, the auto pop-in mode is sufficient. If you need to optimize further, first try to adapt the columns to influence the automatic behavior (sap.m.Column, properties: autoPopinWidth, importance). For example, set the priority for the two or three most important columns to “High” (identifying column, key attribute).

While the pop-in layouts GridLarge and GridSmall make better use of the available width, they also only look good with content that is specifically designed for these pop-in layouts. If you have text-only tables with only one value per column, use the Block layout (sap.m.Table, property: popinLayout).

Place the column header labels in the pop-in area above the corresponding values (sap.m.Column, property: popinDisplay, value: Block). This avoids alignment issues with different content. Be aware that the labels get top-aligned with the adjacent content.
Only place the label next to the corresponding value under the following conditions (sap.m.Column, property: popinDisplay, value: Inline):

  • The values are text-only (no input fields, icons, images, micro charts, and so on)
  • The available space is at least the double the width of size S.

This avoids truncation or “over-wrapping” of the labels and content.

If a column does not have a column header text (for example, if it always contains the same button with its own label), do not show the header text as a label in the pop-in area either (sap.m.Column, property: popinDisplay, value: withoutHeader). If you forget this setting, you will see an empty space followed by a colon (“:”).

Information
The GridSmall and GridLarge layouts are not available in all browsers. If the chosen layout is not available, it is automatically changed to Block layout.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the responsive table. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning
The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

  • The number of rows in the table
  • The number of displayed columns
  • The complexity of the cell content (for example, simple text vs. complex charts)
  • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
  • The browser being used

Table Title

Implement the table title by using a title control in a toolbar.

Use a table title only if the title of the table is not indicated in the surrounding area. Do not use a table title if it simply repeats text that is already above the table. For example:

  • A pricing conditions table is the only control on a tab labeled Pricing Conditions.
  • A section or subsection on an object page contains only one table.

Use a table title if you need the item count, table toolbar, or variant management. To avoid repeating text, feel free to use generic text as a table title, such as Items.
Exception: If the surrounding area contains the table title, and both the item count and toolbar can be added to the surrounding area, no additional table title is needed.
Example: An object page (sub-)section contains only one table. In this case, add the item count and the table toolbar to the (sub-)section header.

Developer Hint
Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table.

If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

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)

The item count in the table title includes all the visible items that a user can reach by scrolling. Group headers are not included.

Remove the item count in the table title if there are zero items. Do not use an item count together with “growing mode”.

If possible, keep the title bar sticky (sap.m.Table, property: sticky).

Table title with item count
Table title with item count

Selection

If the click area for the row is being used for another purpose (such as navigation), it cannot be used for selecting the row. In this case, use the “single select left” selection mode, which offers a radio button as an additional click area for each row. To avoid confusion, make sure that the first data column does not contain radio buttons in default delivery.

In all other single selection cases, use the selection mode “single select master”.

For all single selection modes, make sure that one item is initially selected. Otherwise, the user cannot return to the initial state. A selected item can only be deselected by selecting another item.

In multiple selection mode, do not show checkboxes in the first data column in the default delivery to avoid confusion. Offer the Select All checkbox for (de)selecting all items the user can reach by scrolling.

Don't
Single selection left - Do not show radio buttons in the first column in the default delivery
Single selection left - Do not show radio buttons in the first column in the default delivery
Don't
Multiple selection - Do not show checkboxes in the first column in the default delivery
Multiple selection - Do not show checkboxes in the first column in the default delivery
Do
Use the selection mode
Use the selection mode "single select left" if clicking the row is used for something else (such as navigation)
Do
Use the selection mode
Use the selection mode "single select master" in all other single-selection cases
Developer Hint
Select All is only applied to items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded, such as items added via lazy loading with growingScrollToLoad. This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

To process all items, listen to the selectionChange event and to its selectAll flag. This indicates whether the Select All checkbox was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

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 three to five columns if the responsive table is shown within the flexible column layout. Use about eight columns if using the full screen width, depending on the content.

If the responsive table does not fit into the width provided:

  • 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 into the width provided, 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, no column header label is needed as long as at least one column still has a column header label.

Use controls that wrap and support wrapping with hyphenation, such as text (with wrapping and hyphenation enabled). Do not use controls that truncate.

Keep column headers sticky.

Do
Wrap column headers
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 (rarely used)
Accepted: Link as column header text (rarely used)
Accepted if responsiveness is taken into account: Text plus search field
Accepted if responsiveness is taken into account: Text plus search field

If a column cell contains several fields, use an umbrella term in the column header (such as Address for fields like Street, ZIP Code, and City).

For text and ID fields, use a generic label (for example, Employee for Name and ID).

If none of these are possible, separate the labels with “/” (for example, Name / Status).

For boolean values, such as checkboxes, find a descriptive text for the column header.

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.

Exception: Secondary information in a column always follows the alignment of the main information.

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

Left-align status information.

Left-align status information
Left-align status information

Center-align icons.

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
Use top-alignment where possible
Use top-alignment where possible
Don't
Do not use top alignment if it doesn't make sense
Do not use top alignment if it doesn't 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 table 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
If displayed as a link, use the whole text as the link
If displayed as a link, use the whole text as the link

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
Is displayed as a link, use only the first line as the link
Is displayed as a link, use only the first line as the link

If there is more than one key identifier (for example, First Name and Last Name), display these columns first and show the values in bold text.

Several key identifiers
Several key identifiers

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 and support hyphenation.

For example, use text.

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 to offer edit mode, change your text controls (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 – Inline
Interactive controls – Inline

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

Flag and Favorite

Place the flag or favorite marker in the first column (in the default delivery). To change the settings, users need to drill down into the object itself.

Item marked as a favorite
Item marked as a favorite

Empty Tables

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

Examples:

  • If a table is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the table with data.
  • If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    To start, set the relevant filters.
  • If a table is used together with a filter bar and the filter does not return results, use the following text:
    No data found. Try adjusting the filter settings.

Adapt the texts above if:

  • The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of filter settings).

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 contains 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. To do this, use an object status control with the error state (sap.m.ObjectStatus, property: state, value: sap.ui.core.ValueState.Error).

In addition, highlight the row accordingly (sap.m.ListItemBase, property: highlight).

A modified item with an error
A modified item with an error

To show that an item is locked, use a transparent 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, you can show a highlight indicator next to the item. The highlight indicator can indicate:

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It doesn’t tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted items using status colors
Highlighted items using status colors
Highlighted items using industry-specific (indication) colors
Highlighted items using industry-specific (indication) colors

Numbers and Units

If the following conditions all apply, show the unit of measurement in the column header:

  • The unit of measurement is the same for all rows
  • A single cell contains only one amount with the unit of measurement
  • The column header does not scroll away

In all other cases, show the unit of measurement together with the corresponding amount within the row.

Show the unit of measurement in the same column as the corresponding amount.

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 table width is narrow, 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)

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, it is not accessible, since there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.

Use drag and drop only in addition to existing visible UI elements
Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within the table, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop targets in between items
Drop targets in between items

Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on values in a column, the dropped item needs to take on the value of the target group for the corresponding column. If this is not wanted, do not allow users to rearrange items in grouped tables.

Example:
A table is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Don't
Do not combine rearranging items with grouping, unless you know exactly what you're doing.
Do not combine rearranging items with grouping, unless you know exactly what you're doing.

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

The context menu can be triggered for the whole table or per row.

Actions

To trigger actions on multiple items, use a multiselection table (sap.m.Table, property: mode, value: sap.m.ListMode.MultiSelect), and offer the corresponding actions on the table toolbar. Keep the table toolbar sticky (sap.m.Table, property: sticky).

Do not offer actions for 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. One example would be an Add to Cart button in a shopping application. 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 a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.
Inline actions
Inline actions

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Give users the option to apply the action anyway or to cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element – States.

If the action was applied, and if the items are still available, keep them selected.

Message for an action that applies to a part of a selection
Message for an action that applies to a part of a selection
Place actions near to the objects to which they belong
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

For adding items, place an Add or Create text button on the table toolbar.

  • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
  • Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the table, with a visual highlight at the beginning of the row.

There are three options for adding an item after the Add button is pressed. In order of priority (most recommended first), these are:

  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 just a few columns and no option to hide columns.
  2. Open a dialog for larger tables with up to 8 editable 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 that cannot be handled by a dialog (for example, tables with more than 8 columns). When the user presses Save in the footer toolbar of the create page, navigate back to the table.

A new item can have three different states:

  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 to keep the item visible.
  3. As soon as the responsive table is sorted, filtered, or grouped again, the action is also applied to the new item. It then also loses the visual highlight.

In the context of the draft handling new items are not saved on table level, but rather with the entire draft.

For more details, see the guidelines for managing objects (including subarticles).

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 highlighted, still the first item
Saved new item, still highlighted, still the 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.

For details, see mass editing.

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)

Sort

For the default sort settings, sort by the column that identifies the row, which is usually the first column in default delivery. From this column, use the primary data point.

If you offer sorting, offer it for each data point. In other words, allow sorting by both the primary and secondary information in a column. Allow sorting in both directions, ascending and descending. The descending sort order must always be the exact reverse of the ascending sort order.

For each data point, provide a meaningful sort order. For example:

  • Sort text alphabetically
  • Sort numbers by their value
  • Sort status information by the severity of the status:
    • Ascending: Sort status information from positive to negative, with neutral last.
    • Descending: Sort status information from negative to positive, with neutral first.
Object status sorted ascending, with neutral status last
Object status sorted ascending, with neutral status last
Object status sorted descending, with neutral status first
Object status sorted descending, with neutral status first
    • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
    • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.
Object status sorted ascending and alphabetically, from positive to negative with neutral last
Object status sorted ascending and alphabetically, from positive to negative with neutral last
Object status sorted descending and alphabetically, from negative to positive with neutral first
Object status sorted descending and alphabetically, from negative to positive with neutral first

Filter

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.

Keep the info bar sticky (sap.m.Table, property: sticky).

Developer Hint
To display the current filter settings on the info bar, consider using the list formatter (sap.ui.core.format.ListFormat).
Filtered table
Filtered table

Group

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

If there is no grouping value, show the following text:
[Label of the grouped column]: (Not Available)

This is the case if you have a group of items that don’t have a value for the grouped column.

Grouped table, with missing grouping value
Grouped table, with missing grouping value

Persist the view settings. When a user reopens the app, show the responsive 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.

If all columns are hidden, the table shows a corresponding “no data” text.

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.

Tables in Object Pages

To show a table in the object page content area, use the responsive table.

A responsive table with up to 20 expected items can be displayed right away, without lazy loading.
If you expect the table to have more than 20 items, use one of the following 3 options:

  1. Lazy loading (More button): Use this option if you expect to have up to 100 items.
  2. Tab navigation: If you expect to have more than 50 to 100 items, but less than 400, use the object page with tab navigation instead of anchor navigation. Put the table on a dedicated tab.
  3. Navigation to a list report: If you expect the table to have more than 400 items, or if the tab approach is unsuitable, restrict the number of items in the table itself to a reasonable amount. To provide the user with a way to work with the entire table, offer navigation to a separate list report containing the full table.

For all of the three options mentioned above, we recommend providing a search, and if feasible, sort and filter capabilities for the table in the object page. Grouping should be avoided.

For more information on the use of tables within the object page, see the Tables section of the Object Page article.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting table data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button
'Export to Spreadsheet' menu button

Paste

To paste data from the clipboard to the table, the browser functionality for paste can be used (CTRL + V or browser context menu).

  • If the focus is on row level, the app has to take the data from the clipboard and add it to the corresponding controls within the table.
  • If the focus is on an editable control within the table, the control gets the data automatically.

Pasting via context menu does not work if a custom context menu is used.

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 for a large 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: inset 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.
  • The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). 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

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 for a master-detail scenario using the flexible column layout, as well as in popovers or dialogs. For certain use cases, lists can also be used in the dynamic page layout.

Usage

Use the list if:

  • You want to display a homogeneous set of basic data.
  • You need to sort, group, or filter simple datasets.
  • 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 datasets that need to be extensively sorted, grouped, filtered, or edited. In this case, use a table.
  • You work with complex hierarchies. In this case, 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, since they are usually used to navigate to the item details. For custom list items, you can also wrap the texts, 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 the preferable method for 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

Avoid empty lists. If necessary, provide instructions on how to fill the list with data (sap.m.List/ sap.m.ListBase, properties: noDataText, showNoData).

Examples:

  • If a list is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the list with data.
  • If a list is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    No filters set. To start, enter your search and filter settings and run the search.
  • If a list is used together with a filter bar and the filter does not return results, use the following text:
    No items found. Check the search and filter settings.

Adapt the texts above if:

  • The standard text is not precise enough for your use case (for example, no search is offered, only the search is offered).
  • You are using the live search (no Go button in the filter bar). In this case, leave out “run the search”.
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).
Empty list
Empty list

Count

List items can have a count, which is located on the far right of a row. You can use the count in simple lists, such as those that contain standard list items, to indicate how many subitems the user can expect when navigating to 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

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

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted items using status colors
Highlighted items using status colors
Highlighted items using indication colors
Highlighted items using indication colors

Behavior and Interaction

There are several ways to interact with the list and its list items:

List Level

Scroll

The height of the list is defined by the number of items it contains. It does not have its own scroll container, but is scrolled together with the app.

If the list 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 triggered by scrolling (preferred), or by clicking the More button.

When the user scrolls, the title and the filter infobar can stick to the top of the surrounding layout container (sap.m.List, property: sticky).

Information
The “sticky” feature comes with some limitations:

  • It is not available on all browsers. In non-supporting browsers, the corresponding areas are not fixed on top of the surrounding layout container while scrolling.
  • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the list is placed within the object page.
  • If the focus is set to a sticky area, the list is automatically scrolled to top.

Sticky title
Sticky title

Mode

The list can have several modes. The respective property (Mode) allows the following selection methods:

  • None
  • SingleSelectMaster (used to pick one item with no additional indicator, as in the master list for a master-detail scenario with the flexible column layout)
  • 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). The Shift key can be used to select a range.
  • Delete (used to delete items from the list using a delete indicator on the far right)
Developer Hint
In multiple selection mode, users can (de)select all items using the shortcut CTRL+A. This only affects items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded (for example, items added via lazy loading with growingScrollToLoad). This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

To process all items, listen to the selectionChange event and to its flag selectAll. This indicates whether CTRL+A was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

List with explicit single selection
List with explicit single selection
List with multiple selection
List with multiple 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

Line Item Level

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 pencil appears on the far right, indicating that something can be changed. The user can only click the pencil.)
  • Detail and active (same as “detail”, but the item itself is also clickable)

The example shows how all these types are visualized.

All list item types: inactive, detail, navigation, active, detail and active
All list item types: inactive, detail, navigation, active, detail and active

Indicate Navigated Item

When multi-selection is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case only (multi-selection list with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.ListItemBase, property: navigated).

Navigated item
Navigated item

Swipe

You can provide a swipe feature (sap.m.List, properties: swipeDirection, swipeContent) for approving or deleting items quickly without having to look at the details. Swiping is possible in both directions (left to right / right to left). You can provide different actions for each direction. Because swiping is only available on touch devices, only offer it as an additional feature. Swiping should never be the only way to perform the action.

List with swipe action
List with swipe action

Context Menu

The context menu can be triggered for the list or per item.

It gives users an alternative way of modifying the focused elements by giving access to context-specific functions.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or SHIFT+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

List - context menu
List - context menu

Drag and Drop

One or several items can be repositioned within a list or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop
Whole item as drop target
Whole item as drop target

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 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 without separators
List without separators

Guidelines

Text Length

When you use the list in the first column of the flexible column layout, keep the texts as short as possible and only as long as necessary. If you expect large numbers, use formatting instead.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the list. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning
The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

  • The number of rows in the table
  • The number of displayed columns
  • The complexity of the cell content (for example, simple text vs. complex charts)
  • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
  • The browser being used

Custom List Items

If none of the list items provided suits the requirements of your app, you can also create a custom list. If you choose this option, ensure that your custom list item is responsive when resized.

When creating custom list items, take the following guidelines into account, as needed:

Radio Button

Only use radio buttons if they are absolutely necessary. One example would be if you want to distinguish single selection from navigation. This is a rare case in which visible radio buttons for single selection are allowed.

Actions

To trigger actions on single items, show the actions on a toolbar above the list. Do not offer actions on multiple items if the list is expected to have fewer than 10 items in most cases.

The following actions on single items must always be inline:

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

You can combine delete and edit actions, or delete and navigation actions. However, edit and navigation actions cannot be combined.

To trigger actions that are independent of the selection, show the actions on a toolbar above the list. For example: AddCollapse AllExpand 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). When clicked, active items trigger an event that can be handled by the app (for example, to open a dialog). Selection of items and expanding/collapsing a node do not trigger the event, and are handled by the tree. Do not use the active item type 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 the single selection master.

Add Items

For adding items, place an Add or Create text button on the table toolbar.

  • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
  • Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the table, with a visual highlight at the beginning of the row.

For more information, see the guidelines for managing objects (including subarticles).

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Let users choose whether to apply the action anyway or cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element – States.

If the action was applied and the items are still available, keep them selected.

Message for action which applies to a part of a selection
Message for action which applies to a part of a selection

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, it is not accessible, since there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.

Use drag and drop only in addition to existing visible UI elements
Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within the list, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop targets in between items
Drop targets in between items

Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on values, the dropped item needs to take on the corresponding value of the target group. If this is not wanted, do not allow users to rearrange items in grouped lists.

 

Example:

A list is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Don't
Do not combine rearranging items with grouping, unless you know exactly what you're doing
Do not combine rearranging items with grouping, unless you know exactly what you're doing

Export to Spreadsheet

Apps can provide a menu button for exporting list data to a spreadsheet (for example, on the relevant toolbar). For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button
'Export to Spreadsheet' menu button

Resources

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

Elements and Controls

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.
  • 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 uses “lazy loading”.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.Table, property: rowHeight).

The grid table is optimized to allow faster scrolling within the first 1000 items.

Scroll bar
Scroll bar

Select

Selection Mode

Selection for a grid table depends on the chosen selection mode. The following options are available:

No selection: Items cannot be selected. (property: selectionMode = None)

A non-selection grid table
A non-selection grid table

Single selection: One item in the grid table can be selected. A row selector column is shown. (property: selectionMode = Single)

A single-selection grid table
A single-selection grid table

Multiple selection: One or more items can be selected. 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. The Shift key can be used to select a range.

For multiple selection, you can choose between two variants.

  • Multi-toggle mode (property: selectionMode = MultiToggle)
  • Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)

These variants behave differently when the user selects more items than are currently loaded in the front end.

Multi-toggle

In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end. All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

Multi-selection plug-in

If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:

  • By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
  • You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
    • The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and you can display a corresponding message (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
    • If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets.
  • If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.
Information
When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

  • The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
  • The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.Table, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

A multiselection grid table
A multiselection grid table
Using the multi-selection plug-in with a limit
Using the multi-selection plug-in with a limit

Selection Behavior

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 option for multi-selection grid tables if clicking a row or a cell is not used for anything else.
  • RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
  • RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection grid tables if clicking a row or a cell is not used for another purpose, 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).
  • Touch interaction: The user 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

Drag and Drop

One or several items can be repositioned within a table or moved to other UI elements using drag and drop operations (sap.ui.table.Table, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop
Whole item as drop target
Whole item as drop target

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows (like group headers). Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or SHIFT+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Grid table with a context menu
Grid table with a context menu

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). Do not wrap.

Cell
Cell

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

Implement the table title by using a title control in a toolbar.

Use a table title only if the title of the table is not indicated in the surrounding area.

Do not use a table title if it simply repeats text that is already above the table. For example:

  • A pricing conditions table is the only control on a tab labeled Pricing Conditions.
  • A section or subsection on an object page contains only one table.

Use a table title if you need the item count, table toolbar, or variant management. To avoid repeating text, feel free to use generic text as a table title, such as Items.
Exception: If the surrounding area contains the table title, and both the item count and toolbar can be added to the surrounding area, no additional table title is needed.
Example: An object page (sub-)section contains only one table. In this case, add the item count and the table toolbar to the (sub-)section header.

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

The item count 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.

Developer Hint
Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table.

If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

Multiple Selection

  • We strongly recommend using the multi-selection plug-in. This ensures that all items selected using Select All or as part of a range are included – even if some items were not initially loaded in the front end. This is not the case if you use the multi-toggle option.
  • Do not limit the range selection for the multi-selection plug-in unless you have to.
    • If the dataset is small and/or completely available in the front-end, set the limit property to 0 to enable the Select All option and allow users to select any range.
    • If you have a large dataset, set a limit on the number of selected items to avoid performance issues. Also bear in mind that some actions won’t be helpful if the dataset is too big (for example, a delete operation on 2 million database entries).
  • If you set a limit, also display the corresponding message when the user selects more items at once than the limit allows (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification).
Information
When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

  • The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
  • The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

  • In multiple selection mode (multi toggle), do not show checkboxes in the first data column in the default delivery to avoid confusion.
Don't
Do not add checkboxes to the first data column in the default delivery
Do not add checkboxes to the first data column in the default delivery

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 the column width for its initial visible content, including the column header texts. If this is not possible (for example, if showing the full texts would result in extremely wide columns), let the texts truncate. End users can change the width of the column to read the full text, as needed.

Maintain a constant column width and avoid adjusting it automatically when the content changes.

Always keep to one line of text. Do not wrap.

Don't
In the default delivery, the initial visible content should not be truncated
In the default delivery, the initial visible content should not be truncated
Don't
Never wrap texts
Never wrap texts

Column Headers – Best Practices

For each column, provide a label in the column header. In the default delivery, do not truncate the column header texts. Only let the text truncate if showing the full text would make the column too wide. Never wrap the text.

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

Left-align status information.

Left-align status information
Left-align status information

Center-align icons.

Left-align micro charts.

XS micro charts in condensed mode
XS micro charts in condensed mode

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

  • Show the ID in a separate column. Use this format if users need to sort, group, or filter by both the string and the ID.
  • Show the ID in brackets after the corresponding string. In this case, sorting, filtering and grouping is available for either the string or the ID. Use this format only if users don’t need to sort, filter, and group by both values.
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
If displayed as a link, use only the text as the link, not the ID
If displayed as a link, use only the text as the link, not the ID
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 one column - If displaying a link, show the whole string as the link (text and ID)
Text and ID in one column - If displaying a link, show the whole string as the link (text and ID)

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. Do not wrap.

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

Micro Charts

Use only the following micro charts: Bulletcomparisonstacked bar. When using micro charts, use them in size XS.

Micro charts in a grid table
Micro charts in a grid table

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

Examples:

  • If a table is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the table with data.
  • If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    To start, set the relevant filters.
  • If a table is used together with a filter bar and the filter does not return results, use the following text:
    No data found. Try adjusting the filter settings.

Adapt the texts above if:

  • The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of filter settings).
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 contains an error, for example, within the global edit flow, add the string Contains errors in the Editing Status column and highlight the row accordingly. 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

Show the unit of measurment on the column header, if the unit of measurement is the same for all rows. If not, show the unit of measurement within the row.

Drag and Drop

If you offer drag and drop for rearranging items within the table, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop targets in between items
Drop targets in between items

Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

Don't
Do not combine rearranging items with sorting
Do not combine rearranging items with sorting

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, it is not accessible, since there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.

Use drag and drop only in addition to existing visible UI elements
Use drag and drop only in addition to existing visible UI elements

When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on values in a column, the dropped item needs to take on the value of the target group for the corresponding column. If this is not wanted, do not allow users to rearrange items in grouped tables.

Example:
A table is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Don't
Do not combine rearranging items with grouping, unless you know exactly what you're doing.
Do not combine rearranging items with grouping, unless you know exactly what you're doing.

Context Menu

Use the context menu only as a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar). Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

The context menu can be triggered for the table, row, or cell. However, we do not recommend using context menus for cells: because the content of a cell is a different touch target than the cell itself, opening a cell context menu via touch is quite hard, even in cozy mode.

Do not combine context menus with condensed mode: editable controls fill the entire space inside a cell. Because of this, context menus cannot be opened at all with touch or mouse interaction.

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. One example would be an Add to Cart button in a shopping application. 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. Provide a separate column per action. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

To trigger navigation on line item level, choose one of the following options:

  • Use a link for the attribute that identifies the row. Clicking the link triggers the navigation.
  • Add the RowActions column and show the navigation indicator (  ) at the end of the row. The navigation arrow triggers the navigation.

Special case: Multi-selection in a master-detail scenario
When a multi-selection table is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case, you can display a “navigated” indicator to show which item is currently open.

Use the RowActions column only for one or both of the following actions:

  • Navigate to details page ( )
  • Delete ( )

The RowActions column does not provide a column header text. It is fixed and will not scroll away. Users also cannot personalize this column.

Navigate to details page
Navigate to details page

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

For adding items, place an Add or Create text button on the table toolbar.

  • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
  • Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the table, with a visual highlight at the beginning of the row.

For more details, see the guidelines for managing objects (including subarticles).

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Let the user choose whether to apply the action anyway or cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element – States.

If the action was applied, and if the items are still available, keep them selected.

Message for an action that applies to a part of a selection
Message for an action that applies to a part of a selection

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.

For more information, see Mass Editing.

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.

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

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.

Sort

To display the current sort state, an icon is shown in the column header of the most recently 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.

Column, sorted ascending
Column, sorted ascending
Column, sorted descending
Column, sorted descending

The descending sort order must always be the exact reverse of the ascending sort order. For each column, provide a meaningful sort order. For example:

  • Sort text alphabetically
  • Sort numbers by their value
  • Sort status information by the severity of the status:
    • Ascending: Sort status information from positive to negative, with neutral last.
    • Descending: Sort status information from negative to positive, with neutral first.
Object status sorted ascending, with neutral status last
Object status sorted ascending, with neutral status last
Object status sorted descending, with neutral status first
Object status sorted descending, with neutral status first
    • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
    • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.
Object status sorted ascending and alphabetically, from positive to negative with neutral last
Object status sorted ascending and alphabetically, from positive to negative with neutral last
Object status sorted descending and alphabetically, from negative to positive with neutral first
Object status sorted descending and alphabetically, from negative to positive with neutral first

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

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

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.ui.table.Table, aggregation: rowSettingsTemplate)

Highlighted items
Highlighted items

Tables in Object Pages

In the object page, we advise against using the analytical, grid, and tree tables. Instead, use a responsive table and offer navigation to a list report with the table types mentioned above.

For more information on the use of tables within the object page, see the Tables section of the Object Page article.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting table data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button
'Export to Spreadsheet' menu button

Paste

The browser paste function can be used to paste data from the clipboard to the table (CTRL+V or browser context menu).

  • If the focus is on row level, the app has to take the data from the clipboard and add it to the corresponding controls within the table.
  • If the focus is on an editable control within the table, the control gets the data automatically.

Pasting via the context menu does not work if a custom context menu is used.

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.
  • The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). 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

Grid List

As with the list and the responsive table, the grid list displays a set of items. In contrast to both controls, the grid list displays the items not in rows, but in a grid.

The grid list is usually used as an alternative view for a list or table. It is ideal for displaying images, charts, object cards, and other content, which profit from more height (but less width).

Grid List
Grid List

Usage

Use the grid list if:

  • Your content is “visual” and profits from the rectangular format of the items. This is true for e.g. images, charts, and object cards.
  • The focus is on items, not on cells. The grid list shows complete items.
  • You want to display a homogeneous set of basic data.
  • You need to sort, group, or filter simple data sets.
  • As an alternative view for tables or lists, if the content profits from the different format.

Do not use the grid list if:

  • Your content is not appropriate for a card-like format. For example, do not use the grid list for displaying a wall of text. Use a table instead.
  • 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.
  • Data needs to be structured in a hierarchical manner. In this case, a tree might be more appropriate.
  • 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 the CSSGrid.
  • You want to manage complex datasets that need to be extensively sorted, grouped, filtered, or edited. In this case, use a table.

Responsiveness

The responsiveness of the grid list results from the underlying grid. The underlying grid is defined by rows and columns. Columns can have a minimum and maximum or a fixed size. Whenever an additional column fits on the screen, it will be added. If a column does not fit on the screen anymore, it will be removed. Items are re-layouted accordingly.

Optionally, there can be different configurations for the underlying grid based on breakpoints, for example based on the device types.

To define the grid layout and behavior, you can use one of the pre-defined layouts:

  • Grid box layout: Adds a variable number of columns depending on the available screen width. Columns have either a fixed width or can “breathe” slightly. All rows have the same height, and all items are the same size.
  • Responsive column layout: The number of columns depends on breakpoints (4 columns for size S, 8 for size M, 12 for size L, and 16 for size XL). The width of the columns grows or shrinks with the available screen space until the next breakpoint is reached. The row height of the grid is determined by the height of the highest item in the row. The number of rows and columns taken up by an item can differ.

Alternatively, you can define your own grid. This gives you much greater flexibility to influence both the layout and the (responsive) behavior of the grid.

The underlying grid defines the available space per item. The width can differ pending on the screen width (“breathing”) or be fixed. The height can differ pending on the content of the item or be fixed. “Breathing” items make better use of the available screen space and is therefore recommended. Make sure, that the item adapts to the resulting width / height, for example by

  • Re-layouting the item content
  • Hiding less important information
  • Re-sizing content, such as images or charts.

Items can use one ore more grid cells. Items can also be different sizes (for example, to allow for varying text lengths/wrapping in different items).

Size S
Size S
Size M
Size M
Size L
Size L

Components

  • The title bar holds the title and, an item counter. Instead of a title bar you can use a toolbar, including title, counter, variant management and actions.
  • Optionally, a filter infobar should appear when the grid list is filtered and shows information on the filter settings.
  • The collection of grid list items, layouted on a grid, occupies the main part of the grid list.
  • 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. Use More only, if content is shown below the grid list.
  • The footer can contain additional static text information.
Schematic visualization of the grid list
Schematic visualization of the grid list

Title Bar

The title bar contains the title of the grid list and an item counter

Title Bar
Title Bar

Instead of the title bar, a toolbar can be used instead. If done so, use a title control to display the title and item count. Variant management and actions can be added in this case. The toolbar can contain entry points for the view settings dialog, as well as view switches in the form of a segmented button, and buttons for actions like for example Add, or Edit.

Toolbar instead of title bar
Toolbar instead of title bar

For the title, keep the following in mind:

  • Use a title if you need the item count, toolbar actions, or variant management. To avoid repeating text, feel free to use generic text as a title, such as Items.
  • Do not show the title bar at all, if all elements (title, item count, variant management, toolbar) are available in the surrounding area.
    Example: An object page (sub-)section contains only one grid list. In this case, add the item count and the toolbar to the (sub-)section header.
Developer Hint
Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table. If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

For displaying the item count, use the following format:

[title text] ([count])

for example:

Items (2,534)

For the item count, keep the following in mind:

  • include all the items that a user can reach by scrolling except group headers.
  • Remove the item count if there are zero items.
  • Do not show a count on the title bar, if a More button is used. Show the count on the more button instead.

If possible, keep the title bar sticky (sap.m.GridList, property: sticky).

Filter Infobar

Beneath the toolbar, display a filter infobar (which itself is a special toolbar) if the grid list is filtered.

Filter infobar
Filter infobar

Items

The items (sap.f.GridListItem) are placed on a grid. To specify the design of items, it is recommend (but not mandatory) to follow the guidelines for object cards. Be aware that the item itself is responsible for its own responsiveness.

Use the grid list only, if your content profits from the format. This can apply to images, charts, but also to object cards or quick views. Another option is to mimick the format (but not the visual) of existing objects (e.g. business cards).

A grid list item can contain any content. This includes single controls, or a combination of controls (e.g. by using layout containers).

When designing an item,

  • Use the grid list item as starting point and make sure that the content adapts responsively to a changing item width / height.
  • Although the grid list can technically work with other list items (e.g. the standard list item), do not use them. They are not responsive enough for being used in a grid. In addition, selectors, navigation indicators and other elements are layouted differently (optimized for the list, not for the grid list).
  • Take care that an item can be identified, e.g. by adding a title, and if needed a sub title.
  • To show a string with an ID as identifier, use the title for the string, and the subtitle for the ID.
  • For status information, use semantic colors on foreground elements.
  • Avoid truncation. Use controls that wrap the text and configure them accordingly.
  • If an edit mode is needed, change your text controls (labels, text, and links) to input fields or other appropriate editable 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 item.

Not all items have to follow the same structure. This could be the case if one item is locked, but another item is in edit mode. Another example is to show a set of objects of different types in the same grid list.

Example for a grid list item
Example for a grid list item
Another example for a grid list item
Another example for a grid list item

Highlight

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

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry- / process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users what exactly is wrong. Make sure that you provide this information within the item, ideally in the same color.

For details on the usage of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted item
Highlighted item

States

To show that an item is unread, use the corresponding flag (sap.m.GridList, property: showUnread, sap.f.GridListItem, property: unread). This shows most of the content in bold font.

Unread item next to a read item
Unread item next to a read item

To show that an item has been modified, for example, within the global edit flow, add the string (Modified) near the item identifier.

A modified item
A modified item

To show that a modified item contains an error (for example, within the global edit flow), add the string (Contains errors) near the item identifier. To do this, use an object status control with the error state (sap.m.ObjectStatus, property: state, value: sap.ui.core.ValueState.Error). In addition, highlight the item accordingly (sap.f.GridListItem, property: highlight).

An item with an error
An item with an error

To show that an item is locked, use a transparent button with the corresponding icon and the text Locked by [Name] near the item identifier. The user can click 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 near the item identifier. The user can click the button to open a popover showing the timestamp of the last change.

An item with draft state
An item with draft state

Show only one state at any one time.

“More” Button

The More button loads more items to the front end if not all items have yet been loaded.

"More" button

Footer

The footer can be used to display additional static information relating to the content.

Grid list footer
Grid list footer

Behavior and Interaction

Scroll

The height of the grid list is defined by the number of items it contains. It does not have a scroll container on its own but is scrolled together with the page. When the user scrolls the page, the title bar and filter infobar can stick to the top of the surrounding layout container (sap.m.GridList, property: sticky).

Information
The “sticky” feature comes with some limitations:

  • It is not available on all browsers. In non-supporting browsers, the corresponding areas (title bar, filter infobar) are not fixed on top of the surrounding layout container while scrolling.
  • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the grid list is placed within the object page.
  • If focus is set to a fixed column header, the grid list is automatically scrolled to top.

Sticky toolbar
Sticky toolbar

Showing more items

If the grid list works in a “growing” mode, it only loads a few items at first. Additional items are only loaded (and rendered) on request. This request can either be triggered by scrolling (preferred), or by clicking the More button. Use the latter one only if content follows below the grid list. Use the “growing mode”, if more than 200 items are expected to be displayed.

If using the “More” button,

  • show the number of items already loaded and (if possible) the total number items below the text More.
  • do not show an item count on the title bar. Use the count on the More button instead.

In any case, if the “growing mode” is used, do not show more than 1,000 items overall.

Select

A grid list can have one of the following selection modes (sap.m.GridList/ sap.m.ListBase, property: mode):

  • None: Items cannot be selected (sap.m.ListMode.None).
    Beware: Items can still use the sap.m.ListType “navigation”, which allows click handling on specific items. Only use this option if the click triggers navigation to a corresponding item details page.
  • Single selection master: One item in the grid list can be selected. Items are selected by clicking the whole row. The single select master mode has no obvious visual cues, such as checkboxes or radio buttons. It only provides a light blue background for the selected state. Because of this, it can barely be differentiated from grid lists without selection (mode: None). Single select master is the preferred mode for single selection. (sap.m.ListMode.SingleSelectMaster).
Selected item in
Selected item in "single selection master"
  • Single selection left: One item in the grid list can be selected. For this, the grid list provides radio buttons on the left side of each item. Only use this mode if a click on the whole item is being used for something else, such as navigation. (sap.m.ListMode.SingleSelectLeft). Even in this case, prefer single select master and synchronize the selection with the navigation, so that the navigated item is also the selected item.
  • Multi selection: Users can select one or more items. For this, the grid list provides checkboxes on the left side of each item. (sap.m.ListMode.MultiSelect). The Shift key can be used to select a range. Try to avoid combining multi selection with navigation.
An unselected and a selected item in
An unselected and a selected item in "multi selection"

For all single selection modes, make sure that one item is initially selected. Otherwise, the user cannot return to the initial state. A selected item can only be deselected by selecting another item.

Click an Item

The whole item can be clickable. An event is fired by clicking the item (anywhere where there is no interactive control inside the item). Apps can react on the event, for example, by opening a dialog (sap.f.GridListItem, 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 grid list in “single select master” mode.

Drag and Drop

One or several items can be repositioned within a grid list or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

When using drag and drop, keep the following in mind:

  • Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, it is not accessible, since there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items.
  • If you offer drag and drop for rearranging items within the grid list, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).
  • Be aware that due to the re-arrangement of the items which happens after an item is dropped, it is not always clear where the item will finally be placed.
  • When dropping items from outside the grid list, adapt the size of the drop indicator to match the target layout of the item (sap.f.dnd.GridDropInfo, property: dropIndicatorSize).
  • Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.
  • When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on a specific data point, the dropped item needs to take on the value of the target group for the corresponding data point. If this is not wanted, do not allow users to rearrange items in grouped grid lists. Example:
    A grid list is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Loading Data

To indicate that the grid list is currently loading items, use the busy state. (sap.m.GridList, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Empty Grid Lists

Try not to display an empty grid list. If there is no way around this, provide instructions on how to fill the grid list with data (sap.m.ListBase, properties: showNoData, noDataText).

Examples:

  • If a grid list is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the grid list with data.
  • If a grid list is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    To start, set the relevant filters.
  • If a grid list is used together with a filter bar and the filter does not return results, use the following text:
    No data found. Try adjusting the filter settings.

Adapt the texts above if:

  • The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of filter settings).

Context Menu

You can attach a context menu to a grid list. The context menu gives users an alternative way to modify the whole grid list or an individual item by providing access to context-specific actions. A context menu is opened by right-clicking (mouse), long press (touch devices), or via keyboard using the context menu key or SHIFT+F10. If a control inside a grid list is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar). Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

Be aware that using the context menu overrides the browsers context menu, which can no longer be opened.

Group

If grouped, a group header is displayed (sap.m.GroupHeaderListItem) above all items which belong to the corresponding group. The group header is not interactive.

A grouped grid list
A grouped grid list

Guidelines

Actions

To trigger actions on multiple items, use a multi-selection grid list (sap.m.GridList, property: mode, value: sap.m.ListMode.MultiSelect), and offer the corresponding actions on the toolbar of the grid list. Keep the toolbar sticky (sap.m.GridList, property: sticky).

In rare cases, you can also offer the corresponding actions in the footer toolbar. Do this only if the grid list is the only area on the screen to which actions can be applied and if the actions are finalizing.

Do not offer actions for multiple items if the grid list is expected to have fewer than 10 items in most cases.

To trigger actions on a single item only (sap.m.GridList, property: mode, value: sap.m.ListMode.SingleSelectMaster), the action can also be shown within the item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every item 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. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

The following actions on single items must always be in-line:

  • Delete: Use the “Delete” mode of the grid list (sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This places a Delete button at the right side of an item. Clicking 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 grid list and therefore cannot be used together with single selection or multi-selection.
Delete button
Delete button
  • Navigation: Use the “Navigation” item type (sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This places a Navigation indicator at the right side of an item and the entire item becomes clickable. Use this to navigate to a new page containing item details. In rare cases, you can also use this for the category navigation pattern without navigating to another page. By contrast, clicking an interactive control within an item does not trigger the navigation event. Instead, the corresponding control handles the click event.
    “Navigation” is an 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: Use the “Detail” list item type (sap.f.GridListItem, property: type, value: sap.m.ListType.Detail). This places an Edit icon at the right side of an item. Clicking the button triggers the edit event. Use this event to switch the corresponding 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

From these three actions (delete, navigation, and edit), you can combine delete and edit, or delete and navigation. Edit and navigation cannot be combined.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the responsive table. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning
The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

  • The number of rows in the table
  • The number of displayed columns
  • The complexity of the cell content (for example, simple text vs. complex charts)
  • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
  • The browser being used

Add Items

  • Place the Add or Create text button on the toolbar of the grid list.
    • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
    • Use Add if the item already exists and is merely added or assigned to the current object.
  • Place new items always as the first item of the grid list.
  • Use highlight (information state) on the new item.

After pressing the Add button, there are three possibilities for adding an item, which should be considered in the following priority:

  • Add the item inline. Create an empty, editable item as the first item of the grid list. Show the Save button on the toolbar of the grid list. This option is recommended for simple scenarios where just a few input fields have to be filled.
  • Open a dialog for items where up to 8 input fields need to be filled. Save the new item at the dialog level.
  • Navigate to a new page. This behavior should only be used for very complex scenarios that cannot be handled by a dialog (for example, creating complex objects). When the user presses Save in the footer toolbar of the create page, navigate back to the grid list.

There are three different states of a new item:

  • New: The item was just created and is still in edit mode. It is highlighted with a visual indicator (information state).
  • Recent: The item was saved but is still highlighted and displayed as the first item of the grid list. Current filter, sort and group criteria are ignored since the item should remain visible.
  • As soon as the grid list is sorted, filtered, or grouped again, the new item is handled accordingly and loses the visual highlight, but not before.

In the context of the draft handling new items are not saved on grid list level, but rather with the entire draft.

Export to Spreadsheet

Mass Editing

  • Provide multiselection (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.

For details, see mass editing.

Paste

To paste data from the clipboard to the grid list, the browser functionality for paste can be used (CTRL + V or browser context menu).

If the focus is on item level, the app has to take the data from the clipboard and add it to the corresponding controls within the items.

If the focus is on an editable control within an item, the control gets the data automatically.

Pasting via context menu does not work if a custom context menu is used.

View Settings

  • Provide individual buttons for each of the following settings on the toolbar of the grid list: sort, filter, group.
  • Clicking one of these buttons opens the view settings dialog or P13nDialog dialog with just the relevant page inside.
  • When closed, apply the settings to the grid list accordingly.

Keep the following in mind:

  • Do not offer any of these features if the grid list 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 on the toolbar of the grid list. Use the filter bar instead.
  • Always use only the view settings which are really needed. For example, do not offer grouping if it does not support your use case well.
  • Persist the view settings. When a user reopens the app, show the grid list with the same sort, filter, and group settings as last defined by this user.

Sort

  • For the default sort settings, sort by the item title, which is usually the identifier of an item.
  • If you offer sorting, offer it for each data point available in the item. Allow sorting in both directions, ascending and descending. The descending sort order must always be the exact reverse of the ascending sort order.
  • For each data point, provide a meaningful sort order. For example:
    • Sort text alphabetically
    • Sort numbers by their value
    • Sort status information by the severity of the status:
      • Ascending: Sort status information from positive to negative, with neutral last.
      • Descending: Sort status information from negative to positive, with neutral first.
      • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
      • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Filter

  • To display the current filter state, use the infobar below the title. Clicking the infobar opens the filter page of the corresponding dialog.
  • Show the infobar only if the filter settings are not shown somewhere else. For example, do not show the infobar for settings taken in the filter bar or in a select placed in the toolbar of the grid list.
  • If the infobar is shown, provide an option to reset all corresponding filters on the infobar.
  • Keep the infobar sticky (sap.m.GridList, property: sticky).
Developer Hint
To display the current filter settings on the infobar, consider using the list formatter (sap.ui.core.format.ListFormat).

Group

  • 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 data point]: [Grouping Value]
  • If there is no grouping value, show the following text:
    [Label of the grouped data point]: (Not Available)
    This is the case if you have a group of items that don’t have a value for the grouped data point.

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection,

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action, if it can be applied to all selected items.
  • Enable the action, if it can be applied to a part of the selected items. If the action is triggered, show a message that informs the user about how many items will be affected. Provide the choice to apply the action anyway or to cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element States.

If the action was applied, and if the items are still available, keep them selected.

Message for action which applies to a part of a selection
Message for action which applies to a part of a selection

To trigger actions that are independent of the selection, show the actions on the toolbar of the grid list. Examples of such actions are add, edit (in the sense of changing the whole table to edit mode), sort, filter, and group.

To trigger a default action on the whole item, use the “Active” or “DetailAndActive” list item type (sap.f.GridListItem, 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 Active 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.

Grid Lists in Object Pages

A grid list with up to 20 expected items can be displayed right away, without lazy loading.

If you expect the grid list to have more than 20 items, use one of the following 3 options:

  • Lazy loading (More button): Use this option if you expect to have up to 100 items.
  • Tab navigation: If you expect to have more than 50 to 100 items, but less than 400, use the object page with tab navigation instead of anchor navigation. Put the grid list on a dedicated tab.
  • Navigation to a list report: If you expect the grid list to have more than 400 items, or if the tab approach is unsuitable, restrict the number of items in the grid list itself to a reasonable amount. To provide the user with a way to work with the entire grid list, offer navigation to a separate list report containing all items.

For all of the three options mentioned above, we recommend providing a search, and if feasible, sort and filter capabilities for the grid list in the object page. Grouping should be avoided.

For more information on the use of grid lists within the object page, see Object Page – Tables.

Properties

sap.f.GridList

The following additional properties are available for the grid list:

  • The property: inset adds a margin on all sides of the grid list.
  • The property: headerText is a simple way to set the title for the grid list. However, this excludes the following:
    • A separate toolbar
    • variantManagement
  • 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 grid list.
  • The property: includeItemInSelection uses a click on the whole item to select the corresponding item if the grid list is in a selection mode. This competes with other settings like “Navigation” or “Active” and should therefore not be used in combination with these two settings.
  • 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 grid list is set to busy state)
  • The property: modeAnimationOn does not have any effect. Do not use it.
  • The property: showSeparators does not have any effect. Do not use this property.
  • The property: swipeDirection does not have any effect. Do not use this property.
  • The property: rememberSelections leaves items selected even if they are currently not 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 grid list to a busy state. While in busy state, the whole grid list 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 grid list has been set to this state. Use the default value.
  • The property: visible shows the grid list (“true”) or hides it (“false”).
  • The property: tooltip provides a tooltip for the whole grid list. Do not use it.

sap.f.GridListItem

The following additional properties are available for sap.m.ColumnListItem:

  • The property: selected allows an item to be selected programmatically.
  • The property: counter shows a number on the right side of an item. This is used in cases like showing the number of subitems.
  • 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 item. 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 table is 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

The analytical 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 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 for 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).

The analytical table is optimized to allow faster scrolling within the first 1000 items.

Scroll bar
Scroll bar

Select

Selection for an analytical table depends on the chosen selection mode. The following options are available:

No selection: Items cannot be selected. (property: selectionMode = None)

Analytical table without item selection
Analytical table without item selection

Single selection: One item in the analytical table can be selected. A row selector column is shown. (property: selectionMode = Single)

Analytical table with single selection
Analytical table with single selection
  • Multiple selection: One or more items can be selected. The analytical 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. The Shift key can be used to select a range. For multiple selection, you can choose between two variants.
    • Multi-toggle mode (property: selectionMode = MultiToggle)
    • Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)

    These variants behave differently when the user selects more items than are currently loaded in the front end.

    Multi-toggle

    In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end. All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

    Multi-selection plug-in

    If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:

    • By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
    • You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
      • The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and a message can appear (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
      • If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets.
    • If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.
Information
When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

  • The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
  • The “minimum limit”: Internally, the analytcial table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.AnalyticalTable, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

Analytical table with multiple selection
Analytical table with multiple selection
Using the multi-selection plug-in with a limit
Using the multi-selection plug-in with a limit

Selection Behavior

An item can be selected in different ways, depending on the configuration of the analytical table (sap.ui.table.Table, property: selectionBehavior):

  • Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection tables if clicking a row or a cell is not used for anything else.
  • RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
  • RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection tables if clicking a row or a cell is not used for another purpose, 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 data currently visible and the label of the column header (sap.ui.table.AnalyticalColumn, property: Autoresizable).
  • Touch interaction: The user clicks 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

Drag and Drop

One or several items can be moved to other UI elements using drag and drop operations (sap.ui.table.AnalyticalTable, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop
Whole item as drop target
Whole item as drop target

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). Do not wrap.

Cell
Cell

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows (like group headers). Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

By default, the analytical table provides a context menu on the group headers (for example, Expand, Collapse, …). Otherwise, no default context menus are provided.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or SHIFT+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Analytical table with context menu
Analytical table with 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

Implement the table title by using a title control in a toolbar.

Use a table title only if the title of the table is not indicated in the surrounding area.

Do not use a table title if it simply repeats text that is already above the table. For example:

  • A pricing conditions table is the only control on a tab labeled Pricing Conditions.
  • A section or subsection on an object page contains only one table.

Use a table title if you need the item count, table toolbar, or variant management. To avoid repeating text, feel free to use generic text as a table title, such as Items.
Exception: If the surrounding area contains the table title, and both the item count and toolbar can be added to the surrounding area, no additional table title is needed.
Example: An object page (sub-)section contains only one table. In this case, add the item count and the table toolbar to the (sub-)section header.

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

The item count 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.

Developer Hint
Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table.

If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

Multiple Selection

  • We strongly recommend using the multi-selection plug-in. This ensures that all items selected using Select All or as part of a range are included – even if some items were not initially loaded in the front end. This is not the case if you use the multi-toggle option.
  • Do not limit the range selection for the multi-selection plug-in unless you have to.
    • If the dataset is small and/or completely available in the front-end, set the limit property to 0 to enable the Select All option and allow users to select any range.
    • If you have a large dataset, set a limit on the number of selected items to avoid performance issues. Also bear in mind that some actions won’t be helpful if the dataset is too big (for example, a delete operation on 2 million database entries).
  • When setting a limit, also display the corresponding message when the user selects more items at once than the limit allows (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification).

In multiple selection mode (multi toggle), do not show checkboxes in the first data column in the default delivery to avoid confusion.

Don't
Do not add checkboxes to the first column
Do not add checkboxes to the first column

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 the column width for its initial visible content, including the column header texts. If this is not possible (for example, if showing the full texts would result in extremely wide columns), let the texts truncate. End users can change the width of the column to read the full text, as needed.

Maintain a constant column width and avoid adjusting it automatically when the content changes.

Always keep to one line of text. Do not wrap.

Don't
In the default delivery, the initial visible content should not be truncated
In the default delivery, the initial visible content should not be truncated
Don't
Never wrap texts
Never wrap texts

Column Headers – Best Practices

For each column, provide a label in the column header. In the default delivery, do not truncate the column header texts. Only let the text truncate if showing the full text would make the column too wide. Never wrap the text.

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

Left-align status information.

Left-align status information
Left-align status information

Center-align icons.

Left-align micro charts.

XS micro charts in condensed mode
XS micro charts in condensed mode

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 a separate column. Use this format if users need to sort, group, or filter by both the string and the ID.
  • Show the ID in brackets after the corresponding string. In this case, sorting, filtering and grouping is available for either the string or the ID. Use this format only if users don’t need to sort, filter, and group by both values.
Text and ID in two columns – Allows sorting, filtering, and grouping for both
Text and ID in two columns – Allows sorting, filtering, and grouping for both
If displayed as a link, use only the string as the link, not the ID
If displayed as a link, use only the string as the link, not the ID
Text and ID in one column – Sorting, filtering, and grouping only by the text
Text and ID in one column – Sorting, filtering, and grouping only by the text
If displayed as a link, use the whole text as the link
If displayed as a link, use the whole text as the link

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. Do not wrap.

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

Micro Charts

Use only the following micro charts: Bullet, comparison, stacked bar. When using micro charts, use them in size XS.

Micro charts in an analytical table
Micro charts in an analytical table

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

Examples:

  • If a table is initially empty, provide at least a basic text:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the table with data.
  • If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
    To start, set the relevant filters.
  • If a table is used together with a filter bar and the filter does not return results, use the following text:
    No data found. Try adjusting the filter settings.

Adapt the texts above if:

  • The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
  • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of filter settings).
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 contains an error, for example, within the global edit flow, add the string Contains errors in the Editing Status column and highlight the row accordingly. 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

If the unit of measurement is the same for all rows, show the unit of measurement in the column header. Otherwise, show the unit of measurement within the row.

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, drag and drop is not accessible, since there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose, such as (toolbar) buttons.

Use drag and drop only in addition to existing visible UI elements
Use drag and drop only in addition to existing visible UI elements

Do not use drag and drop for rearranging items in the analytical table. The analytical table is mainly used for grouping items and for calculating the totals per group and column. Moving items to another group also means that a value of the dropped item changes: because grouping is based on values in a column, the dropped item needs to take on the value of the target group for the corresponding column.

Example:
A table is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. Because changing the value in this way doesn’t make sense, rearranging items is not permitted in analytical tables.

Don't
Do not use drag and drop for rearranging items in the analytical table
Do not use drag and drop for rearranging items in the analytical table

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar). Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

The context menu can be triggered for the table, row, or cell. However, we do not recommend using context menus for cells: because the content of a cell is a different touch target than the cell itself, opening a cell context menu via touch is quite hard, even in cozy mode.

Do not combine context menus with condensed mode: editable controls fill the entire space inside a cell. Because of this, context menus cannot be opened at all with touch or mouse interaction.

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. One example would be an Add to Cart button in a shopping application. 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. Provide a separate column per action. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

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.

To trigger navigation on line item level choose one of the following options:

  • Use a link for the attribute that identifies the row. Clicking the link triggers the navigation.
  • Add the RowActions column and show the navigation indicator (  ) at the end of the row. The navigation arrow triggers the navigation.

Special case: Multi-selection in a master-detail scenario
When a multi-selection table is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case, you can display a “navigated” indicator to show which item is currently open.

Use the RowActions column only for one or both of the following actions:

  • Navigate to details page ( )
  • Delete ( )

The RowActions column does not provide a column header text. It is fixed and will not scroll away. Users also cannot personalize this column.

Navigate to details page
Navigate to details page

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

For adding items, place an Add or Create text button on the table toolbar.

  • Use Create if the button adds a brand new item that doesn’t yet exist on the database.
  • Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the table, with a visual highlight at the beginning of the row.

For more details, see the guidelines for managing objects (including subarticles).

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

  • Enable the action if it always works, regardless of whether or not items are selected.
  • Enable the action if it can be applied to all selected items.
  • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Let users choose whether to apply the action anyway or cancel the action.
  • Only disable the action if it can be applied to none of the selected items.

For more details, see UI Element States.

If the action was applied and the items are still available, keep them selected.

Message for action which applies to a part of a selection
Message for action which applies to a part of a selection

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.

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.
Interactive controls – Inline
Interactive controls – Inline

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

 

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

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.

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

The descending sort order must always be the exact reverse of the ascending sort order.

For each column, provide a meaningful sort order. For example:

  • Sort text alphabetically
  • Sort numbers by their value
  • Sort status information by the severity of the status:
    • Ascending: Sort status information from positive to negative, with neutral last.
    • Descending: Sort status information from negative to positive, with neutral first.
Object status sorted ascending, with neutral status last
Object status sorted ascending, with neutral status last
Object status sorted descending, with neutral status first
Object status sorted descending, with neutral status first
    • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
    • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.
Object status sorted ascending and alphabetically, from positive to negative with neutral last
Object status sorted ascending and alphabetically, from positive to negative with neutral last
Object status sorted descending and alphabetically, from negative to positive with neutral first
Object status sorted descending and alphabetically, from negative to positive with neutral first

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]

If there is no grouping value, show the following text:
[Label of the grouped column]: (Not Available)

This is the case if you have a group of items that don’t have a value for the grouped column.

 

Set the property collapseRecursive to “false” to keep subgroups expanded even after collapsing and expanding the parent group.

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)

When aggregating amounts with different units of measurement, show an asterisk (*) in the aggregation rows.

When sorting an aggregated column, only the leaf nodes of a group are included by default. If each measure column currently displays a single unit of measurement, the order of the groups can also be affected.

For example:
Let’s assume that table items are grouped by Country/Region and aggregated by Total Net Amount. If you sort the Total Net Amount column in descending order, the largest total net amount is shown first.

Warning
Only enable sorting by totals if each column has a single unit of measurement. This prevents inconsistencies in the sorting behavior, which depends on user settings, such as filter settings or the columns currently displayed.
Developer Hint
To allow sorting by totals, the following conditions must be met:

  1. For each measure column, multiple units must not occur in the displayed data, regardless of whether or not totals are shown.
  2. The autoExpandMode of the AnalyticalBinding must be set to Sequential. Note that the default is Bundled.

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

Highlight Items

To show that an item needs attention, you can display a highlight indicator in front of the item. The highlight indicator can be used to indicate:

  • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
  • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
  • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.ui.table.AnalyticalTable, aggregation: rowSettingsTemplate)

Highlighted items
Highlighted items

Tables in Object Pages

In the object page, we advise against using analytical, grid, and tree tables. Instead, use a responsive table and offer navigation to a list report with the table types mentioned above.

For more information on the use of tables within the object page, see the Tables section of the Object Page article.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting table data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button
'Export to Spreadsheet' menu button

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.
  • The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). 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

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 or micro 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:

  • Business actions (app-specific)
  • Generic actions
    • 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

Business Actions

If needed, you can define your own actions for the app using transparent text buttons only. If multiple actions are required, sort them, starting with the most important action (= primary action) on the left. You can emphasize the primary action using a ghost button.

More Information:

Chart toolbar with business actions
Chart toolbar with business actions
Chart toolbar with emphasized primary business action
Chart toolbar with emphasized primary business action

Perspective Switch / Chart Title (Generic)

Chart toolbar - Perspective switch
Chart toolbar - Perspective switch

The perspective switch is left-aligned in the toolbar. It can be used to switch between different dimensions. We recommend using a select control, but any other dropdown control can be used as well.

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 using a short chart description followed by the dimensions:

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.

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

To help visually impaired users, always offer the zoom feature on the chart toolbar. Two icon buttons depicting a magnifying glass are then displayed. These buttons are positioned just to the left of the full screen icon. When the user clicks the Zoom In or Zoom Out button, the chart automatically zooms accordingly.

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)

In addition to zooming, the app can use the full screen mode of the chart container (property: FullScreen). The full screen button is located between the personalization button and the view switch.

The user can switch between embedded and full screen mode via this toggle button. When maximized, the chart’s full screen icon is replaced by the exit full screen icon.

In full screen mode, the chart and toolbar occupy the entire screen width and cover the shell bar.

Icon Usage

The two screen modes are represented by the following icons.

Full screen icon
Full screen icon
Exit full screen icon
Exit full screen 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 toolbar with actions.
  • Try to put the actions as close to the content as possible.
  • Use appropriate tooltips to label icon buttons in the chart toolbar.

Resources

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

Link

A link (also known as hyperlink) is an interactive text element.

Different links visualizing the various link types
Different links visualizing the various link types

Usage

Use a link if:

  • You want to navigate to another page.
  • You want to trigger an event.
  • You want to point to an object or person. If so, you can either navigate to the object’s/person’s details or display them in a quick view after the link is triggered.

Do not use a link if:

  • You could use a button to trigger the action instead.
  • The link text is the key identifier of an object. In this case, use an actionable object identifier instead.
  • There is no target or reference to be linked to.

Responsiveness

The link can either truncate or wrap. Favor wrapping over truncating and keep the link text as short and meaningful as possible.

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

Wrapped (first) and truncated (second) link
Wrapped (first) and truncated (second) link

Types

There are four different link types:

  • Default
  • Emphasized
  • Subtle
  • Link with icon
Guidelines
Use a meaningful link text that indicates what will happen when the user interacts with the link (for example, Open Sales Order). Avoid texts such as Click Here or Link, as these do not meet accessibility standards.
Default, emphasized, subtle link, and link with icon
Default, emphasized, subtle link, and link with icon

Default

Use a default link if you want to display a simple link.

Default links
Default links

Emphasized

Use an emphasized link for extraordinarily important links that need to attract the user’s attention quickly.

Emphasized links
Emphasized links

Subtle

Use subtle links to distinguish between important (default) and less important (subtle) links when the app page is full of various links (10+). Subtle links allow you to improve the visual hierarchy in large data lists and tables.

Subtle links
Subtle links

Link with Icon

Use the link with icon when the user expects and profits from the icon in the UI context.

Guidelines
Use the link with icon only if the icon is internationally well-known and easily understood. For example,  (world),   (calendar), or (theater).
Links with icon
Links with icon

Behavior and Interaction

To trigger the event or navigation, the user clicks the link. It provides visual feedback for “hover” and “focused” states.

If the link cannot be triggered due to, for example, a disabled content area part, display the disabled state.

Default, hover, focused, and disabled link
Default, hover, focused, and disabled link

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

The filter bar filters item lists and tables according to various filter criteria. You can use it for both simple and complex lists, regardless of their size. To handle complex lists with multiple filters, the filter bar provides predefined, customizable filter sets (variants).

Filter bar within the dynamic page
Filter bar within the dynamic page
Information
The filter bar now supports the dynamic page. Do not use the filter bar in the sap.m.Page for new SAP Fiori apps. For more information on the differences, see the filter bar guideline for version 1.52.

Responsiveness

Because tables appear in many apps, from simple to complex ones, the filter bar needs to run on all form factors. While the main concept of the filter bar remains stable across the devices, its responsive design adapts the control’s behavior to match the ability of each device.

Size S (Smartphones)

Expanded filter bar (size S)
Expanded filter bar (size S)
Collapsed filter bar (size S)
Collapsed filter bar (size S)
Filter dialog (size S)
Filter dialog (size S)

Size L (Desktop)

Expanded filter bar (size L)
Expanded filter bar (size L)
Collapsed filter bar (size L)
Collapsed filter bar (size L)
Filter dialog (size L)
Filter dialog (size L)

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)

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 Not Filtered.
Collapsed filter bar
Collapsed filter bar

Expanded Filter Bar

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

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

Filter/input controls
Filter/input controls

When designing the filter bar, pick the simplest input control that works for your use case. Avoid unnecessary complexity in the filter bar.

If there is a predefined list for single or multiple selection, use the select control or combo box control. For temporal information, you can use the date picker or date range selector. To help the user enter a valid value for multi-input fields, you can enable suggestions.

For a comprehensive overview of when to use which input field, see Selection Controls – Overview.

Use the value help control only as a last resort. It is especially beneficial 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.

Developer Hint
For development information, see data types for the smart filter bar.

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.

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.

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.

Saving a New Variant

You can save new filter variants either in the variant selector or in the filter dialog.

Once you have changed an existing variant, an asterisk (*) is displayed next to the current variant name, indicating its “dirty state”.

You can either save the adapted variant with the current name (overwrite), or save it under a new name.

Option 1 – Variant Selector

Open the variant selector and choose Save As. Type your desired variant name into the input field and select OK.

Save new variant in variant selector
Save new variant in variant selector

Option 2 – Filter Dialog

Choose Adapt Filters to open the filter dialog. Choose Save from the footer toolbar and type your desired variant name into the input field. Select OK.

Save new variant in filter dialog
Save new variant in filter dialog

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 datasets. In this case, consider making certain default filters mandatory to help the user avoid loading very large datasets unnecessarily.

For list reports and overview pages, ensure that mandatory filter fields always have default values. Otherwise, users will see error messages when the page loads.

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 with default values. 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

Live Update / Manual Update

The filter bar is available in two separate modes: Live update mode and manual update mode.

Live Update

The live update mode is the default 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.

The search is triggered with every letter that is entered, starting with the first letter the user types. The table is updated with the results that match all set filters and include the search term.

Manual Update

In the manual update mode, 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.

Which Mode Should I Use?

We recommend using live update mode, which is more convenient for the user. However, 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 live update mode
Filter bar in live update mode
Filter bar in manual update mode
Filter bar in manual 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

Object Display Components

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

  • Object status: a short text that represents the semantic status of an object
  • Object identifier: a short text that represents the key identifier of an object
  • Object number: a short text that represents the numeric (key) attribute of an object and its unit
  • Object marker: indicates the technical status of an object
From top to bottom: exemplary object status, object identifier, object number, and object marker
From top to bottom: exemplary object status, object identifier, object number, and object marker

Usage

Use the object display components if:

  • You need to display the semantic status of an object: negative, critical, positive, or neutral. Use the object status for this.
  • You want to display the key number of an object. In this case, use the object number and keep the default emphasized setting.
  • You need to display one or more numeric attributes of an object (for example, for objects you want to compare). Use the object number for this.
  • You want to indicate the key identifier of the object. Use the object identifier for this.
  • You want to display the technical state of an object (draft, unsaved changes, locked, favorite, flagged). Use the object marker for this, unless you want to display the status of the object in the business life cycle. In the latter case, consider using the object status instead.
  • You need to show that the current object instance is locked by another user. Use the object marker for this.

Do not use the object display components if:

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

Responsiveness

  • The object status wraps if it is longer than the available screen width.
  • The object identifier text wraps if the size of the screen becomes too small to display the entire text on one line.
  • The object number does not wrap or truncate. For large numbers, you need to consider using the appropriate formatting.
  • The object marker does not wrap or truncate. It comes with different display options: IconAndText, IconOnly and Text. On size S, the display option IconAndText only displays the icon due to lack of space. The other options are displayed as normal.

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

From top to bottom: Wrapping examples for the object status, object identifier, formatted object number, and two versions of the object marker
From top to bottom: Wrapping examples for the object status, object identifier, formatted object number, and two versions of the object marker

Components

Object Status

The object status is a short text that represents the semantic status of an object.

It consists of the following:

  • A semantically colored text indicating its status (property: text). We recommend using this semantically colored text-only option on its own. Check out the How to Use Semantic Colors / Industry-Specific Colors article for color options.
  • An optional icon (property: icon). If you need to have an icon, use one of the following:
     = positive/success
    = critical/warning
    = negative/error
    Note that there is no generic icon for “neutral” across industries. If you have a neutral object status, use the text-only version, a blank icon, or an icon that means neutral in the app’s specific business context.
Text-only object status and icon with text object status
Text-only object status and icon with text object status
  • An optional inverted visualization. Use the inverted object status if the information is crucial for the user’s actions and needs to stand out visually (for example, in table list items).
  • An optional link (property: active). If the object status is used as a link, a hover effect is shown on non-touch devices. Use this feature if the user needs additional information about the status (for example, in a popover). Note that if you use the object status as a combination of icon and text, there is no hover effect for the icon.
Inverted object status (left) and object status in hover state (right)
Inverted object status (left) and object status in hover state (right)
  • An optional larger font (CSS class: sapMObjectStatusLarge). Use this feature if the object status is important in the business context and needs to stand out visually in the page header (for example, key value facets in an object page).
Larger object status
Larger object status
Guidelines

  • In rare cases, an object can have two statuses at the same time. In this case, use the inverted text-only version for the most important status, and the normal text-only version (with an optional icon) for the less important status.
  • If you use the object status in a table, follow the corresponding sorting guidelines.
  • To prevent the text being read as a link, don’t use the blue “information state” for the object status.

Object Identifier

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

It has the following characteristics:

  • A title text (property: title)
  • An optional link (property: titleActive). In this case, the event can open the quick view of the object or a popover for example.
  • An optional additional descriptive text (property: text)
Guidelines

  • The object identifier should be easily readable (preferably the display text and not the ID).
  • If the object’s ID is necessary to distinguish between items that use the same title, it should appear as descriptive text below the title (property: text).

Normal object identifier, object identifier with link, and object identifier with descriptive text
Normal object identifier, object identifier with link, and object identifier with descriptive text

Object Number

The object number is a short text that represents the numeric (key) attribute of an object and its unit.

It consists of the following:

  • A colored text (property: number) based on the semantic color palette. Check out the How to Use Semantic Colors / Industry-Specific Colors article for more details.
  • An emphasized text which you can set to non-emphasized when you use it in the content area (property: emphasized).
  • An optional unit (property: unit).
Emphasized and non-emphasised object numbers
Emphasized and non-emphasised object numbers
Object number used as a semantic attribute (weight)
Object number used as a semantic attribute (weight)
  • An optional larger font (CSS class: sapMObjectNumberLarge). Use this feature if the object number is important in the business context and needs to stand out visually in the page header (for example, key value facets in an object page). Once the large font is applied, the object number can no longer be emphasized.
Guidelines

  • The object number can also be used to visualize other semantic numeric attributes. In this case, they are not emphasized unless they are the key attribute, such as a sum.
  • Emphasize the object number if it is used as a line item status in a table.

Emphasized and non-emphasized object numbers
Emphasized and non-emphasized object numbers

Object Marker

The object marker indicates the technical status of an object and can be interactive. It is enabled for the dynamic page layout, snapping header, object page header, upload collection, and object list item. The technical status can be represented as an icon, with an icon and text, or as text only, depending on the screen size.

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

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

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

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

Developer Hint
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. For details regarding draft handling, please see How to Display the Editing Status in the Draft Handling article.
Icons for draft, unsaved changes, locked, favorite, and flag (from left to right)
Icons for draft, unsaved changes, locked, favorite, and flag (from left to right)
Editing status examples
Editing status 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

Multi-Combo Box

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

Usage

Use the multi-combo box if:

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

Do not use the multi-combo box if:

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

Responsiveness

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

Size S

 Filter bar with multi-combo box - Size S
Filter bar with multi-combo box - Size S
Option list in full screen - Size S
Option list in full screen - Size S

Size M

Filter bar with multi-combo box - Size M
Filter bar with multi-combo box - Size M

Size L

Filter bar with multi-combo box - Size L
Filter bar with multi-combo box - Size L

Also see the section on behavior for mobile devices.

Components

Input Field

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

Dropdown Trigger

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

Option List

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

Components of the multi-combo box
Components of the multi-combo box

Two-Column Layout

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

Multi-combo box with a two-column layout
Multi-combo box with a two-column layout

Behavior and Interaction

Select a Value

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

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

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

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

Developer Hint
With the showitems API, you can open the option list without having the dropdown arrow in a pressed state. Clicking on the arrow again opens the full option list and sets it to pressed state. This way, you can show some items on focus and all items on click.

Input Field

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

Behavior - Sizes M and L
Behavior - Sizes M and L

Choose from Option List

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

Reviewing Tokens

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

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

Multi-combo box - n More
Multi-combo box - n More

If the length of the last selected token exceeds the width of the input field, a label [n] Item/s is shown when the field is not in focus.

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

Multi-combo box - '1 Item' label (desktop)
Multi-combo box - '1 Item' label (desktop)
Multi-combo box - 'n Items' label (Desktop)
Multi-combo box - 'n Items' label (Desktop)

Filtering the Option List

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

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

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

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

Warning
The typeahead input feature is not available for Android devices.
Multi-combo box - Default filtering and auto-complete
Multi-combo box - Default filtering and auto-complete

Grouping

Option list items can be grouped. Visually, the group header is a separate line above the items it groups. It does not currently provide an interaction of its own.

Multi-combo box - Grouping (desktop)
Multi-combo box - Grouping (desktop)
Multi-combo box - Grouping (mobile, Size S)
Multi-combo box - Grouping (mobile, Size S)

Behavior for Mobile Devices

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

Tapping the Arrow

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

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

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

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

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

Input Field on Collapsed List

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

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

Multiple Selected Items

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

Swiping to display tokens
Swiping to display tokens

Copying and Pasting Data from a Spreadsheet or Text File

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

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

Styles

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

Unselected
Unselected
Unselected with predefined placeholder
Unselected with predefined placeholder
Unselected on hover
Unselected on hover
In focus
In focus
Expanded
Expanded
Hover highlighting in list
Hover highlighting in list
Expanded selection
Expanded selection
Expanded multi-selection
Expanded multi-selection
Selected items shown as tokens
Selected items shown as tokens
Error
Error
Warning
Warning
Success
Success
Information
Information

For more information on how to use the different semantic states of the control, see How to Use Semantic Colors.

Guidelines

Label

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

Placeholder

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

Option List

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

Sorting

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

  • Logical: Sort items into a meaningful order. Group related options together and show the most common options first followed by less common options.
Logical multi-combo box
Logical multi-combo box
  • Alphabetical: Sort currencies, names, and so on into alphabetical order. We recommend this for lists with more than eight items.
Alphabetical multi-combo box
Alphabetical multi-combo box
  • Numeric: Sort numeric values into a sequential order with the lowest number first.
Numeric multi-combo box
Numeric multi-combo box
  • Chronological: Sort time-related information into chronological order with the most recent first (if applicable).
Chronological multi-combo box
Chronological multi-combo box

Width

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

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

Unit of Measurement

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

Developer Hint

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

Multi-Combo Box in a Filter Scenario

The multi-combo box can serve as a filter. For example, if the multi-combo box is offered in a table toolbar, and is empty (no tokens selected), the table shows all items. If the user selects picks something in the multi-combo box, the table shows only the matching items.

In addition, users can select or deselect all items from the option list in the multi-combo box using the keyboard. This is done by focusing somewhere in the list and pressing Ctrl+A / Ctrl+Shift+A.

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. To help the user enter a valid value, you can enable the suggestions feature and the value help option.

Usage

Use the multi-input field if:

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

Do not use the multi-input field if:

  • You want the user to select one entry only. In this case, use the input field or combo box instead.
  • You want the user to select from a pre-defined set of options only. In this case, use the multi-combo box instead.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

Size S

  • Cozy mode.
  • When the user taps the multi-input field, a new full screen dialog opens. After tapping in the input field and typing, the suggestions can be selected. When the user makes a selection, the dialog closes and the token is displayed.
  • The user can review the tokens by swiping them to the left or right.
Suggestions on a smartphone (size S)
Suggestions 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

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

Size L

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

Types

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

Behavior and Interaction

Adding a Token

A token can be added using suggestions or value help. As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. The user can accept the autocompleted value by pressing ENTER. The autocomplete property is set by default if suggestions are available, but can also be switched off.

When an item is selected from the suggestions dropdown, the corresponding token is created, and the input field is ready for the next entry. Tokens are placed next to each other on one line.

Warning
The typeahead input feature is not available for Android devices.
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

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

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

Multi-input field - n More (desktop)
Multi-input field - n More (desktop)
Multi-input field - n More (phone)
Multi-input field - n More (phone)

If the length of the last selected token exceeds the width of the input field, a label [n] Item/s is shown when the field is not in focus.

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

Multi-input field - '1 Item' label (desktop)
Multi-input field - '1 Item' label (desktop)
Multi-input field - 'n Items' label (desktop)
Multi-input field - 'n Items' label (desktop)

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

Left/right keyboard cursor
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

Filtering

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

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

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

Multi-input field - Default filtering, autocomplete in the input field is switched off
Multi-input field - Default filtering, autocomplete in the input field is switched off

Copying and Pasting Data from a Spreadsheet or Text File

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

Grouping

You can group the items items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

Multi-input with grouped suggestions
Multi-input with grouped suggestions
Multi-input with grouped tabular suggestions
Multi-input with grouped tabular suggestions

Due to a technical limitation, the group headers are not visible when clicking on the n More text. 

Group headers not shown when clicking on n More items
Group headers not shown when clicking on n More items

Styles

The following images show how the states of the multi-input field are styled.

Unselected
Unselected
Unselected with predefined placeholder
Unselected with predefined placeholder
Unselected on hover
Unselected on hover
In focus
In focus
Selected items shown as tokens
Selected items shown as tokens
Expanded multi-selection
Expanded multi-selection
Error
Error
Warning
Warning
Success
Success
Information
Information

For details on the different states, see UI Element States.

For more information on semantic colors for value states, see How to Use Semantic Colors.

Guidelines

  • Give the control a width that is appropriate for the range of values that are going to be entered. Try to avoid setting a fixed width on this control. Instead, embed it in a proper layout (such as a form, simple form, or grid layout) and work with the layout data property.
  • Provide meaningful labels for all input fields. Do not use the placeholder as a replacement for the label. The placeholder should only provide an additional hint.
  • The multi-input field can currently contain tokens and one free text value. If you allow only validated values, display an error or warning when the user tries to leave the field to indicate that the value entered is invalid, or remove the value.
  • If users try to select an item that has been selected before, we recommend setting an error state and providing a meaningful message.
Multi-input - Error state for an item that has already been selected
Multi-input - Error state for an item that has already been selected
  • You can use the layout options of the form to add the unit of measurement (UoM) after the multi-input control. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.
Developer Hint

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

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

Properties

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

Resources

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

Elements and Controls

Implementation

View Settings Dialog

The view settings dialog helps users to sort, filter, or group data within a (master) list or a table. The dialog is triggered by icon buttons in the table toolbar.

Usage

We recommend making each feature (sort, filter, group) available as a separate button in the table toolbar (see Button Placement below). Each button then triggers a separate dialog. If specifically required, you can combine the dialogs into one with a segmented button acting as tabs to switch between the sort, filter and group options. Note: In a combined dialog, the Reset button resets all tabs.

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

Use distinct icon buttons for the sort, filter, and group settings. Place the icons in the following order:   (Sort) (Filter)  (Group).

Do not place sort, filter, or group buttons in the footer toolbar if they refer to a table.

For detailed information about where to place the sort, filter, and group buttons, see Sort, Filter, Group (Generic) in the table toolbar article.

Sort, Group, and Filter a List

You can also offer the view setting features for a list.

Responsiveness

The popover dialog appears as a modal window on desktop and tablet screen sizes, but full screen on smartphones.

The view settings dialog is a composite control that consists of a modal dialog with a maximum of three tabs with lists of attributes. Each helps the user to either sort, filter, or group a table or list. If the use case requires only a sort feature, for example, you can hide the filter and group tabs.

The dialog is triggered by one of the icon buttons in the table header
The dialog is triggered by one of the icon buttons in the table header
View settings dialog - Size S
View settings dialog - Size S
View settings dialog - Size M
View settings dialog - Size M
View settings dialog - Size L
View settings dialog - Size L

Behavior and Interaction

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

Sort

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.

Users can select attributes using the radio buttons. Clicking OK closes the dialog and shows the table items in the selected order.

If a combined dialog is used, the first tab is the sort feature.

View settings dialog - Sort
View settings dialog - Sort

Filter

The filter dialog can offer a single filter selection list, a multi-filter selection list, or a category list. The category list provides an overview, and allows the user to drill down to detailed filter selection lists.

In a combined view settings dialog, filtering is on the second tab.

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: Weight). You can refine the filter further by selecting subcategories.
The dialog after choosing a general filter category (here: Weight). You can refine the filter further by selecting subcategories.
A table view filtered by 'Weight'. The infobar shows the filter setting.
A table view filtered by 'Weight'. The infobar shows the filter setting.

Filter Selection List – Single Selection

The dialog offers one single-selection list with radio buttons to select a filter. This list is useful for offering a list of preconfigured filters for a specific use, such as “Products with numbers ‘starting between 100 and 200’ with status ‘in stock’ and color ‘green’”.

Filter Selection List – Multi-Selection

You can also offer a filter selection list as a multi-selection list. In this case, the user can choose, for example, all “green” and “red” products.

Selection of multiple filters
Selection of multiple filters

Category List

The filter dialog shows a single list of general filter categories depending on the use case, like Price or Height. The user chooses a category by clicking 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 OK closes the dialog and shows the table items filtered by the selected attribute. The infobar shows which filter has been set.

Free-Form Apps

You can also customize your own filter UIs, for example, to support date picking.

Filter Values

Filters can correspond to single values as well as groups, such as “<100.00 EUR”.

Filter Reset

The refresh button on the filter tab resets all filter settings.

Removing Filters

Be sure to offer an entry such as Not Filtered in a single-selection list. This enables users to remove a set filter.

Group

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.

Via radio buttons or checkboxes, users can choose attributes. Clicking OK closes the dialog and shows the table with items grouped below headers.

In a combined view settings dialog, the group feature is the third tab.

Dialog for choosing an attribute from the group tab
Dialog for choosing an attribute from the group tab
Table view grouped by supplier – Group headers divide the list
Table view grouped by supplier – Group headers divide the list

Naming Group Headers

Be sure to name the group headers as follows: Category Name: Value/Range. For example, Category: Accessories, or Supplier: Red Point Stores.

Guidelines

For opening the dialog from a table toolbar, use different buttons for each function (sort, filter, group). With each button, open the View Settings dialog with just the corresponding tab.

If possible, give users the option not to filter or group. For sorting, this is only necessary if the use case calls for an unsorted list. In all three cases, show this option as the first entry in the list of criteria (remember to include the brackets):

  • (Not Sorted)
  • (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

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.

If the entries are not validated by the application, users can also enter custom values.

Usage

Use the combo box if:

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

Do not use the combo box if:

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

Responsiveness

Size S

Size S
Size S

Size M

Size M
Size M

Size L

Size L
Size L

Also see the section on mobile handling below.

Components

Title

A descriptive heading (1).

Input Field

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

Dropdown Arrow

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

Option List

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

Size S
Size 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 the selection options, such as currencies, country abbreviations, or system abbreviations.

Users can filter both columns simultaneously showing only matching entries.

Combo box with two-column layout
Combo box with two-column layout

Grouping

You can group the items in the suggestion list by a specific attribute and separate them visually with a group header.

The group headers are not interactive.

Grouped suggestion list
Grouped suggestion list
Grouped suggestion list - Size S
Grouped suggestion list - Size S

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). When the user starts typing, the list is filtered accordingly. The first item that starts with the characters entered is highlighted in the list and autocompleted in the input field (3). Up/down moves the highlight in the list and populates the value in the field (4). Selecting a value closes the list of options (5).

Developer Hint
With the showitems API, you can open the option list without having the dropdown arrow in a “pressed” state. Clicking the arrow again opens the full option list and changes the state to “pressed”. This allows you to show some items on focus and all items on click.

Autocomplete

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

Warning
The typeahead input feature is not available on Android devices.

Choose from Option List

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

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

Selecting a value
Selecting a value

Filtering the Option List

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

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

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

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

Combo box - Default filtering and autocomplete
Combo box - Default filtering and autocomplete
Combo box - Default filtering in both columns and autocomplete
Combo box - Default filtering in both columns and autocomplete

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 autocompletion). Clicking the dropdown arrow of the combo box (1) opens in a full-screen dialog (2). The user can now modify the selected entry by clicking the input field of the combo box. The mobile keyboard is then displayed, and the user can begin to enter a new term to filter the option list, also supported by autocompletion (3). The option list closes when the user clicks the OK button at the bottom of the list (4) or selects an item in the list (5).

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

Styles

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

Unselected
Unselected
Unselected with predefined placeholder
Unselected with predefined placeholder
Unselected on hover
Unselected on hover
Arrow on hover
Arrow on hover
Focus
Focus
Expanded
Expanded
Autocomplete
Autocomplete
Error
Error
Warning
Warning
Success
Success
Information
Information
Warning message with long, wrapping text
Warning message with long, wrapping text

For more information on how to use the different semantic states of the control, see How to Use Semantic Colors.

Guidelines

Label

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

Placeholder

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

 

Option List

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

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

Sorting

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

Width

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

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

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

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

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

Unit of Measurement

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

Developer Hint

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

Properties

Selection

When you select a value, there are two events:

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

Resources

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

Elements and Controls

Implementation

Carousel

The carousel allows the user to browse through a set of items. It can display one or several items at a time. From the displayed item or items, the user can navigate to either the next or the previous item.

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

The carousel control is best used for browsing through a set of images. Viewing images one by one helps users to distinguish between different items. In a comparison scenario, it can also be useful to display several items side by side. The carousel is not limited to displaying images; it can contain any sap.m control.

Usage

Use the carousel if:

  • You have strong visual representations of the items you want to display.
  • You want to display items sequentially or side by side.

Do not use the carousel if:

  • The items you want to display are uniform.

Responsiveness

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

On non-touch devices, the user can navigate with the paging buttons displayed on the left and right of the control.

On touch devices, the carousel control makes use of the swipe gesture to navigate through the items. As a result, the paging buttons are not displayed on touch devices.

The paging indicator (when activated) shows on all form factors. The paging indicator wraps if it is too long to fit onto one line.

Carousel - Size S
Carousel - Size S

Carousel - Size M
Carousel - Size M

Carousel - Size L
Carousel - Size L

Layout

The main component of the carousel control is the content area in which the different items are displayed.

The (optional) paging indicator can float above or below the content area.

On non-touch devices, paging buttons either float above the left and right sides of the content area, or appear in the paging indicator area. This is controlled by the arrowsPlacement property.

Displaying multiple items

The layout of the carousel does not change when multiple items are displayed in the content area.

Schematic layout of the carousel
Schematic layout of the carousel

Behavior and Interaction

The content area contains either the current item or a set of items.

Navigation for Single Items

When the user navigates from the current item to another item, the current item is moved out of the content area, and the next or previous item slides in (depending on the direction of navigation).

On touch devices, users navigate with swipe gestures (swipe right or swipe left).

On non-touch devices, users navigate with paging buttons.

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

Paging button – Previous Page
Paging button – Previous Page
Paging button – Next Page (hover)
Paging button – Next Page (hover)

Navigation for Multiple Items

When the user clicks one of the paging buttons, the rightmost or leftmost item is moved out of the content area, and the next or previous item slides in (depending on the navigation direction).

Carousel with multiple items
Carousel with multiple items

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

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 planning calendar can also be used without a row header. In this case, the row header disappears and only the appointments are visible. It can be used to show the calendar of one object. Note that the control was built mainly to compare time slots of different objects. For this reason, the time axis is shown horizontally and, depending on the interval, the appointments might shrink to smaller size. In this case, the text is cut off rather than truncated.

Components

This section describes the various components of the planning calendar.

Parts of the planning calendar
Parts of the planning calendar

The control consists of different parts:

  1. Header
  2. Toolbar
  3. View switch
  4. Navigation
  5. Time strip for hours/days/months
  6. Row header
  7. Row
  8. List item
  9. Interval appointment
  10. Appointment

1. Header

The header contains the toolbar and the navigation.

2. Toolbar

The toolbar consists of the calendar title (optional) and the toolbar actions, including a default view switch. You can add generic and app-specific actions that are relevant for your use case (such as creating an appointment, search, settings, showing the calendar legend, and so on). Always place actions that affect the entire calendar in the toolbar.

For more information, check out the toolbar guideline article.

The generic actions are as follows:

Search
Create Appointment
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)

3. View switch

The view switch allows the user to switch between different time intervals (calendar views). Depending on the number of available calendar views, the view switch can be a segmented button (four views or less) or a select control (five views or more).

The default calendar views are Hours, Days, Months, 1 Week, and 1 Month. The app developer can choose which views to include, depending on the use case, and how many values are shown for each view. App developers can change the default number of values shown, but they should then ensure that the app is still responsive. The app developer can also create custom views.

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

The 1 Month view shows an entire month. On desktop devices, 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.

4. Navigation

The navigation area contains back and forward arrows, the Today button, a date interval link, and the time strip. Clicking the Today button takes the user to the period containing the current day. Clicking the date opens a date picker for direct navigation.

5. Time strip for hours/days/months

The time strip reflects the selected view, and shows the hours, days or months that are currently visible. In all views that show days (Days, 1 Week, 1 Month), you can display calendar weeks in an additional line below the time strip (property: showWeekNumbers).

6. Row header

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

You can also add an action on the row header (event: rowHeaderClick).

7. Row

The row contains all appointments for an object. You can turn the alternating row coloring on or off. By default, the alternating rows option is turned on.

8. List item

The list item contains the row header, row, appointments, and interval appointments. Each row can show different working and non-working days.

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

9. Interval appointment

Each row can also have interval appointments, which differ from half-sized appointments visually and in that they are always at the top of the row. Interval appointments can be used to show appointments that last for a longer period of time, such as vacations or workshops.

You can opt to hide the space reserved for interval appointments if no such appointments exist for that time period.

10. Appointment

Appointments consist of an icon or picture, a title, and a subtitle. Concurrent appointments are shown one above the other. There are two appointment sizes – regular and half size. Half-sized appointments save space, but don’t show a second line with appointment details.

You can define the colors for different appointment types. Appointments can also be set to tentative.

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

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

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

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

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

Planning Calendar Legend

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

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

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

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

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

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

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

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

Planning calendar legend
Planning calendar legend
Developer Hint
To prevent waiting time, app developers should load the sap.ui.unified library.

Behavior and Interaction

To create an appointment, the user must trigger an action by clicking the Create button in the toolbar. You can also configure the control to create a new appointment when the user clicks directly on a row.

The user can click the appointment to see further details. The app development team must define what kind of information is then shown. For example, clicking 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 visible interval, appointments might be smaller and the text cut off. The user can click the appointment to see the details.

View switch

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

Today

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

Back and forward navigation

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

Date picker

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

Snapping Header

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

Header snaps to top when scrolling down
Header snaps to top when scrolling down

Drag and Drop

Drag and drop can be used to move appointments (to enable Drag and Drop use property: enableAppointmentDragAndDrop). Moving an appointment automatically changes its start and end times (for example, if an appointment is scheduled from 1:00-2:00 PM, the user can drag it and change the time from 2:00-3:00 PM) . When dragged, the appointment is shown as a ghost element on the mouse cursor. Drop target areas are indicated to the user with a placeholder.

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

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

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

Combined appointments and interval appointments are not draggable.

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop

Guidelines

Switching the Row Header

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

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

Our guideline is to use the select control in the place of the calendar title. The select control will contain all the attributes that can serve as the row header. When a different attribute is selected, the calendar is rearranged accordingly. You can also add a counter after the list items to indicate how many appointments fall into a specific group.

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

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

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