UI Elements - SAPUI5 Table / List / Tree List

Updated: March 18, 2021
SAPUI5 Version 1.28

List

sap.m.List

Intro

In SAP Fiori, we distinguish between tables and lists. Both usually contain homogeneous data, but lists generally have rather basic data, whereas the data in tables tends to be more complex. Lists are mostly used in the master list section of the master-detail floorplan and in popovers or dialogs, although they can also be used in full-screen floorplans in certain use cases.

Usage

Use the list if:

  • You want to display a homogeneous set of basic data.
  • You need to sort, group, or filter simple data sets.
  • You need to display a single-level hierarchy rather than using a complex tree table to support this simple use case.

Do not use the list if:

  • You want to manage complex data sets that need to be extensively sorted, grouped, filtered, or edited. In this case, you should use the table.
  • You work with complex hierarchies. In this case, you should use a tree.

Responsiveness

The list is like a layout container. You can change its width, but you must also ensure that the items contained in the list adapt whenever the list is resized.

All list item variants available in SAP Fiori already adapt to the respective screen size.

List Item Variants

The list contains various list items. These items can be of various types depending on the use case and on the content they have. SAPUI5 already provides the most common list items in SAP Fiori in the form of controls, although custom list items can also be created if necessary.
All the available list item types behave responsively and adapt to changing screen sizes out of the box. Most of them use truncation if size becomes too limited as they are most often used to navigate to details of the item they currently contain. In the case of custom list items, text wrapping would also be permissible if required.

Object List Item

The object list item is the list item variant used most frequently in SAP Fiori applications. Consisting of a title, key figure, attributes, and a status, it contains the most important information about an object.

The space available for the attributes and status is limited as it should only show crucial information that allows the user to decide which items should be dealt with first.

All essential information about an object is usually provided when the user navigates to the item details.

For more information, see object list item.

Object list items
Object list items

Standard List Item

The standard list item is used for less complex entries, such as when the user selects an item in a dialog. This list item contains an optional image, a title, description, and a single info text (which can contain semantic information).

For more information, see standard list item.

Standard list items
Standard list items

Display List Item

The display list item is the simplest form of a list item and is only capable of showing a label and values. It is seldom used.

For more information, see display list item.

Display list items
Display list items

Action List Item

The action list item allows various actions to be triggered in a dialog. The action list item is not used in the content area.

For more information, see action list item.

Action list item
Action list item

Feed List Item

The feed list item is mainly used in feeds and notes.

For more information, see feed list item.

Feed with feed list items
Feed with feed list items

Input List Item

The input list item allows the user to enter data in a list item. It is seldom used in SAP Fiori apps as forms are usually a more preferable method of entering data.

For more information, see input list item.

Input list item
Input list item

Components

The list control comes with the following main properties:

Header

The header text contains the title of the list. It is usually only used when the list is in the content area.

Footer

The footer text is the last entry in the list, and as such, it scrolls away with the content. Therefore, this property is also seldom used.

Lazy Loading

Like the table, the list also allows lazy loading. The “growing” list property is used for this purpose.

List with header and footer
List with header and footer

Empty List

The noDataText property is used if the list contains no entries. A generic “No Data” text is set by default, but we recommend using specific text if possible.

Empty list
Empty list

Count

List items can have a count, which is located on the far right of a row. It can be used in simple lists, such as those that contain standard list items, to indicate how many subitems the user can expect when navigating on the item.

Standard list items with counter
Standard list items with counter

Read/Unread

You can set an indicator to highlight unread items, making it easier for the user to discover them (property: showUnread = true). If you set this indicator, all texts for the unread items are shown in bold font.

By default, this indicator is switched off, and all list items are displayed in normal font.

Display list item with read and unread items
Display list item with read and unread items

Behavior and Interaction

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

Mode

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

  • None
  • SingleSelectMaster (used to pick one item with no additional indicator, as used in the master list)
  • SingleSelectLeft (used to pick one item using a radio button on the far left)
  • MultiSelect (used to pick several items from the list using checkboxes on the far left)
  • Delete (used to delete items from the list using a delete indicator on the far right)
List with multiple selection
List with multiple selection
List with explicit single selection
List with explicit single selection
List with delete mode
List with delete mode

Grouping

List items can be grouped. The group header is a visually separate line at the top of the items it groups. It does not currently provide an interaction of its own.

Grouped list
Grouped list

Type

The list item type defines the interaction of the list item, which is accompanied by a visual cue.

The items can be one of the following:

  • Active (click event; cursor changes to indicate that)
  • Inactive (no click event; cursor does not change)
  • Navigation (a small arrow appears on the far right, indicating that clicking would navigate)
  • Detail (a pen appears on the far right, indicating that something can be changed there. The user can only click on the pen.)
  • Detail and active (same as “detail”, but also item itself is clickable)

The example opposite shows a visualization of all these types.

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

Swipe

You can also provide a swipe feature (SwipeDirection) for quickly approving or deleting items without having to look at the details. It must only be provided as an addition and not be the only way of performing the action.

List with swipe action
List with swipe action

Styles

The list items can have a header when they are used in a content area. It is also technically possible to change the background of the header and of the list itself. Depending on the use case, the lines between the list items and around the list can also be shown or hidden.

The property Show Separators (All, Inner, None) allows only the outer lines (Inner) or all the lines (None) to be hidden when the list is used as a more structural element within a content area.

List showing no separators
List showing no separators

Guidelines

Text Length

When you use the list in the master area, keep the texts as short as possible and only as long as necessary. If you expect large numbers, use formatting instead.

Custom List Items

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

Radio Button

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

Resources

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

Elements and Controls

Implementation