UI Elements - SAPUI5 Table / List / Tree Grid List

Updated: September 7, 2023
SAPUI5 Version 1.118

Grid List

sap.f.GridList

Intro

The grid list displays a set of items. Whereas the list and the responsive table display the items in rows, the grid list displays the items as rectangular boxes on a grid. This makes it ideal for displaying visual content, such as images, charts, or object cards.

Grid list
Grid list

When to Use

Use the grid list if:

  • You want to display a set of homogeneous items.
  • The rectangular format of the items is better suited to your content than tables or lists.
  • The focus is on complete items, not cells.
  • Your items mimic the format of existing objects (such as business cards).
  • Users need to sort, group, or filter the items.

Don’t use the grid list if:

  • Your content isn’t suitable for a card-like format. If you need to display a lot of detail or if your content is very text-heavy, use a table instead.
  • You expect to show more than 1.000 items. For better performance, use the grid table or analytical table instead.
  • You need an overview of a large amount of data. In this case, consider using a chart.
  • You only need the grid-style layout. In this case, use a layout container, such as the flexible grid.

Components

Grid list components
Grid list components

  1. Title bar or toolbar
  2. Filter infobar (optional)
  3. Items
  4. More button (optional)
  5. Footer (optional)

1. Title Bar

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

Instead of a a title bar, you can use a toolbar. The toolbar can have the following elements:


Title bar
Title bar
Toolbar instead of title bar
Toolbar instead of title bar
Guidelines

  • Use a title if you need the item count, toolbar actions, or variant management. To avoid repeating text, you can also use a generic title text, such as Items.
  • Don’t show the title bar at all if all elements are available in the surrounding area (title, item count, variant management, toolbar).
    Example: An object page section contains only one grid list. In this case, add the item count and the toolbar to the section header.
  • For the item count, apply the following:
    • Use the format: [title text] ([count])
      Example: Items (234)
    • Include all the items that a user can reach by scrolling, except group headers.
    • Remove the item count if there are no items.
    • If you are using a More button, don’t show a count on the title bar. Show the count below the More button instead.
  • Keep the title bar sticky (sap.f.GridList, property: sticky).

Developer Hint
Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the 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.

2. Filter Infobar (Optional)

The filter infobar shows information on the filter settings.

Filter infobar
Filter infobar
Guidelines
Display the filter infobar when the grid list is filtered.

3. Items

A grid list item can contain any content. This can include single controls or a combination of controls (for example, using layout containers).

A grid list can contain different item types. For example:

  • Sales orders and purchase orders
  • Items in display mode and single items in edit mode

You can highlight items and show an item state (such as “unread” or “locked”).

Example of a grid list item
Example of a grid list item
Guidelines

  • Ensure that items can be identified. For example, add a title and subtitle.
  • If the item has an ID and a description, use the title for the description and the subtitle for the ID.
  • Avoid truncation. Use wrapping instead.
  • Since no specific item templates are available, we recommend following the guidelines for object cards.

Another example of a grid list item
Another example of a grid list item

Highlighting Items

To show that an item needs attention, you can display a highlight indicator to the left of the item.
(sap.m.ListItemBase, property: highlight)

Highlighted item
Highlighted item
Guidelines

  • Use highlighting to indicate:
    • A semantic state, such as red for an error or orange for a 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.
  • Provide information within the item to explain why it is highlighted, ideally in the same color. The highlight is just a visual cue. It doesn’t tell users why the item has been highlighted.
  • For more details on the usage of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

Item States

Show the different item states as follows:

State

Unread

How to Display

Shows most content in bold.

sap.f.GridList
property: showUnread

sap.f.GridListItem
property: unread

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

Modified

Add the string (Modified) near the item identifier.

A modified item
A modified item

Error

Add the string (Contains errors) near the item identifier.

sap.m.ObjectStatus
Property: state
Value: sap.ui.core.ValueState.Error


Highlight the item accordingly

sap.f.GridListItem
property: highlight

An item with an error
An item with an error

Locked

Add a transparent button with the corresponding icon and the text Locked by [Name] near the item identifier.

Clicking the button opens a quick view of the person.

A locked item
A locked item

Draft

Add a transparent button with the text Draft near the item identifier.

Clicking the button opens a popover showing the timestamp of the last change.

An item in a draft state
An item in a draft state

“More” Button (Optional)

The More button loads more items. The count below the button indicates the items displayed and the total number of items.

'More' button
'More' button

Footer (Optional)

You can use the footer to display additional static information relating to the content.

Grid list footer
Grid list footer

Behavior and Interaction

This section covers the following topics:

In addition, see the following guidelines for the responsive table:

Grid List:

Grid List Items:

Loading Items

You can load the grid list in “growing” mode.

In “growing” mode, only a limited number of items are loaded when the grid list is initially displayed. Additional items are only loaded (and rendered) on request. This request can be triggered either by scrolling (preferred) or by clicking the More button.

Guidelines

  • To optimize performance, we recommend showing no more than 200 items at once in the grid list.
  • For larger datasets (200 to 1,000 items), use the “growing” mechanism to limit the number of displayed items (property: growing), and make sure that users can filter the data.
  • Ideally, use scrolling to load more items instead of the More button (property: growingScrollToLoad).
  • Use the More button only if content is shown below the grid list.

Warning
The 200 and 1,000 item limits given here 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 items in the grid list
  • The number of displayed data points inside the items
  • The complexity of the data points (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

Scroll

The height of the grid list is defined by the number of items it contains.

The grid list is scrolled together with the page and doesn’t have its own scroll container. When the user scrolls through the page, the title bar and filter infobar can stick to the top of the surrounding layout container
(sap.f.GridList, property:sticky).

Sticky toolbar
Sticky toolbar
Information
The “sticky” feature comes with some limitations:

  • It isn’t available on all browsers.
  • 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.

“More” Button

The More button is the default implementation when growing is switched on (property: growing = true).

'More' button with loaded/total items
'More' button with loaded/total items
Guidelines

  • Only use the More button if your page contains content below the grid list.
  • Below the More text, show the number of items already loaded and (if possible) the total number items.
  • Don’t show an item count on the title bar. Use the count on the More button instead.

Drag and Drop

The grid list offers the same drag and drop features as the responsive table.

However, because the items in the grid list are rearranged after an item is dropped, it isn’t always clear where the item will finally be placed.

Guidelines
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

In addition, see the corresponding guidelines for the responsive table.

Keyboard Navigation

The grid list supports the following keyboard navigation options:

  • Arrow keys: Navigate between items in all directions
  • Page Up / Page Down: Skip several rows
  • Home: Move the focus to the first item
  • End: Move the focus to the last item

Selecting Items

A grid list offers the same selection modes as the responsive table
(sap.f.GridList / sap.m.ListBase, property: mode).

Exception: A Select All checkbox isn’t provided. Users can only select/deselect all items with the keyboard shortcut (CTRL+A).

An unselected and a selected item in
An unselected and a selected item in "multi-selection" mode
A selected item in
A selected item in "single select master" mode
Guidelines

  • For all single selection modes, make sure that one item is initially selected. Otherwise, the user can’t return to the initial state. A selected item can only be deselected by selecting another item.
  • For single-selection list-detail scenarios within the flexible column layout, use the mode “single select master”. Don’t show an additional “navigated” indicator.
  • Avoid the mode “single select left”. It removes the option to click somewhere on the item to select it. Use “single select left” only if you really need two different click areas; a small selection area, and the rest of the item for something else.
  • Never disable the selection checkbox (multiple selection) or radio button (single selection). If an action can’t be performed on a specific item, inform the user after the corresponding action has been triggered. For more information, see Enabling/Disabling Actions.
  • If selecting/deselecting all items is important for your app, add a Select All button to the toolbar. Change the button text to Deselect All if all items are selected.

Clickable Items

The whole item can be clickable. You can define the action triggered by the click, such as opening a dialog (sap.f.GridListItem, property: type, value: sap.m.ListType.Active or sap.m.ListType.DetailAndActive).

Active elements don’t have a visual indicator and therefore can’t be differentiated from non-active elements.

Clicks on interactive controls within the item are handled by the interactive control and don’t trigger the event for the item as a whole.

Guidelines

  • Don’t use the “Active” list item type for navigation, to switch the item to an edit state, or to delete the item.
  • You can combine clickable items with edit and delete actions, but not with navigation.
  • Don’t combine clickable items with single selection. “Active” uses the whole item as a clickable area and therefore can’t be used together with a grid list in “single select master” mode.

Actions

You can offer actions for the entire grid list, single items, and multiple items.

Guidelines
If an action is independent of the selection, show it on the toolbar of the grid list. Examples of such actions are Add or Edit (in the sense of changing all items to edit mode), Sort, Filter, and Group.

To indicate if an action is available, follow the guidelines for enabling/disabling actions.

Actions on Single Items

You can offer actions for single items either on the toolbar or within the item.

Delete, navigation, and edit actions for single items are supported by the grid list control (see below).

Guidelines

  • Offer only one or two actions within the item. 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 if it doesn’t apply to an item.
  • If you offer delete, navigation, or edit actions for single items, always offer them at item level.

Delete:

Use the “Delete” mode of the grid list (sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete).

This places a Delete button (  ) in the top right area of the item.

'Delete' button
'Delete' button
Guidelines

  • Don’t use the “Delete” mode if users typically need to delete multiple items.
  • The “Delete” mode can’t be used with the “single select” or “multi select” selection modes.

Navigation:

Use the “Navigation” item type (sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation).

This places a navigation indicator (  ) in the top right area of the item, and the entire item becomes clickable.

By contrast, clicking an interactive control within an item doesn’t trigger the navigation event. Instead, the corresponding control handles the click event.

Navigation indicator
Navigation indicator
Guidelines

  • Use the navigation action to navigate to a new page containing item details. In rare cases, you can also use the navigation action for the category navigation pattern without navigating to another page.
  • You can’t use the navigation action together with “edit” or in combination with click events for the entire item (“Active”).

Edit: 

Use the “Detail” list item type (sap.f.GridListItem, property: type, value: sap.m.ListType.Detail).

This places an Edit icon (  ) in the top right area of the item. Clicking the button triggers the edit event. Use this event to switch the corresponding item to edit mode.

Edit button
Edit button
Guidelines
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.

You can’t use the “Edit” list item type together with the “navigation” list item type or in combination with click events for the entire item (“Active”).

Actions on Multiple Items

To trigger actions for multiple items:

  • Use a multi-selection grid list.
    (sap.f.GridList, property: mode, value: sap.m.ListMode.MultiSelect)
  • Offer the corresponding actions on the toolbar of the grid list.
  • Keep the toolbar sticky.
    (sap.f.GridList, property: sticky)
Guidelines

  • Don’t offer actions for multiple items if you expect the grid list to usually have fewer than 10 items.
  • For mass editing scenarios, provide an Edit button. When the user clicks this button, open a dialog for editing the corresponding fields for all selected items. For more information, see Mass Edit.
  • In rare cases, you can also offer the corresponding actions in the footer toolbar. Do this only for finalizing actions and if the grid list is the only area on the screen to which actions can be applied.

Errors and Warnings

Error handling must be implemented by the app team.

For details on displaying errors, warnings, and other messages, see Message Handling.

Grid list with errors
Grid list with errors
Guidelines
If the grid list contains items with errors or warnings, show a corresponding message strip above the grid list:

  • On the message strip, provide information about errors or warnings.
  • When issues are solved or when new issues appear, update the message strip accordingly.

Use item states to indicate errors and warnings for single items.

Developer Hint
sap.m.plugins.DataStateIndicator displays a message strip above the table, which shows binding-related messages.

Responsiveness

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

You can also define different configurations for the underlying grid using breakpoints (for example, based on the device types).

Predefined Layouts

To define the grid layout and behavior, you can use one of the predefined 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 ML and L, 16 for size XL, 20 for size XXL and XXXL). 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.

Custom Grid

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 according to the width of the screen (“breathing”) or be fixed. The height can differ according to the content of the item or be fixed.

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

Guidelines
When defining a custom grid:

  • We recommend letting items “breathe” to make better use of the available screen space.
  • Make sure that the item adapts to the resulting width/height. For example:
    • Re-layout the item content.
    • Hide less important information.
    • Re-size content, such as images or charts.

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.
  • Don’t use other list items. They aren’t responsive enough.
  • Use responsive content. For example, use controls that wrap text and configure them accordingly.

Examples

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

Properties

sap.f.GridList

The following additional properties are available for the grid list:

  • inset adds a margin on all sides of the grid list.
  • headerText is a simple way to set the title for the grid list. However, this excludes the following:
    • A separate toolbar
    • Variant management
  • headerDesign affects the appearance of the header if the theme supports it. Leave the default value as it is.
  • footerText adds a small additional row below the table footer or last item. This row can contain text only. Don’t use this property.
  • width defines the width of the whole grid list.
  • 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 therefore shouldn’t be used in combination with these two settings.
  • enableBusyIndicator automatically shows a busy indicator while data is loaded. (In contrast to the busy property, where the application can control when the grid list is set to busy state)
  • modeAnimationOn has no effect. Don’t use it.
  • showSeparators has no effect. Don’t use it..
  • swipeDirection has no effect. Don’t use it..
  • rememberSelections leaves items selected even if they aren’t currently visible (for example, after filtering). If this behavior isn’t wanted, you can set the flag to “false”. However, you should only do so in exceptional cases.
  • busy sets the grid list to a busy state. While in the busy state, the entire grid list can’t be used and items can’t be read due to an overlay.
  • busyIndicatorDelay defines how long a busy state is shown after the grid list has been set to this state. Use the default value.
  • visible shows the grid list (true) or hides it (false).
  • tooltip provides a tooltip for the whole grid list. Don’t use it.

sap.f.GridListItem

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

  • selected allows an item to be selected programmatically.
  • counter shows a number on the right side of an item. This is used to show the number of subitems, for example.
  • Don’t use the busy property.
  • Don’t the busyIndicatorDelay property.
  • visible shows or hides the item.
  • tooltip adds a tooltip to a whole item. The tooltip is only shown on mouse interaction. It won’t work on tablets or smartphones. Don’t use it.

Top Tips

  • Use the grid list only if the content is suitable for a rectangular format.
  • Ensure that items can be identified.
  • Keep your grid and your items responsive. Consider allowing cards of different sizes to avoid content truncation.
  • In your card design, either mimic existing objects like business cards or follow the guidelines for object cards.

Related Links

Elements and Controls

Implementation