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

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.