Archives

Message Toast

A message toast (sap.m.MessageToast) is a small, non-disruptive popup for success messages that disappears automatically after a few seconds.

Usage

Use the message toast if:

  • You want to display a short success message.
  • You do not want to interrupt users while they are performing an action.
  • You want to confirm a successful action.

Do not use the message toast if:

  • You want to display an error or warning message.
  • You want to interrupt users while they are performing an action.
  • You want to make sure that users read the message before they leave the page.
  • You want users to be able to copy the message content to the clipboard (such as a product or transaction number). In this case, use a success message dialog instead.

Responsiveness

The message toast has the same behavior on all devices. However, you can adjust the width of the control, for example, for use on a desktop device.

Layout

Position

The message toast is always centered horizontally at the bottom of the screen.

Message toast on a desktop
Message toast on a desktop

Width

The basic width of the toast is 15 rem. Although the app can adjust the width, we recommend setting it to no more than 35 rem.

For longer success messages, adjust the width of the toast to make the message easy to read (for example, on a desktop device).

Behavior and Interaction

Choreography

When an action is successful, the message toast fades in and out automatically. The timing and duration of the message toast is defined by the app.

Navigation

In some scenarios, the action that triggers the message toast also triggers navigation to a different page (for example, after a save or submit action).

In this case, always navigate first, and then show the message toast on the target page.

Only show the message toast on the same page if no navigation is involved.

Exception: success message dialog

If you need to interrupt users before they leave the current page, do not use the message toast, but a message box (sap.m.MessageBox, property: type – success), which includes a success message. For more information, see message box.

Information
Only put a success message in a message box if your use case requires explicit user interaction, such as copying an order number to process it. We strongly recommend using a message toast where possible.

Animation

Set the duration of the animation according to the length of the message text: the longer the text, the longer the duration should be. The message does not react to the user’s focus.

Guidelines

Message Toast Texts

To make the toast message easy to scan, keep the text as short as possible. Remember that the user will not have time to take in very much detail.

Do not use the word “successfully” in the message text. This is implicit in a success message.

Patterns

For standard actions (such as create, save, delete, or send), we recommend using the following patterns, depending on your use case.

Use Case Use Case Variant Pattern (EN) Example (EN)
Single item Object name is not needed.

Hint: If the name or ID is not crucial feedback in your context, leave it out.

 [object] [action taken] Sales order created
Object name is needed.

Hint: If you mention the object name, you can often leave out the object type (usually obvious in the context).

 [name] [action taken] SAP added to customer group
Multiple items [item count] [objects] [action taken] 2 sales orders were deleted.
Multiple actions Single items, object names are not needed 1 [object] [1st action taken], 1 [object] [2nd action taken] 1 product added, 1 product removed
Single items, object names are needed.

Hint: Only include object names if the user really needs the specific feedback.

 [object] [name] [1st action taken], [object] [name] [2nd action taken] Product A was added, product B was removed.
Multiple items [item count] [objects] [1st action taken], [item count] [objects] [2nd action taken] 2 products added, 3 products removed

Notes:

  • The exact phrasing will depend on your target audience and the conventions in your app family. If an action is repeated regularly by a heavy users, be as brief as possible (for example, Order deleted). If your app is typically for occasional users, a full sentence might be more appropriate (for example, Your request has been sent to the support team.).
  • Bear in mind that long object names can increase the length of the message toast. Remember to allow for this when defining the toast duration. If long or multiple object names make the toast too cumbersome to read, leave them out. If you really need to list them in a success message, use the success message box instead.
Do
Toast without ID
Toast without ID
Don't
Do not use
Do not use "successfully"
Do
Toast with item count
Toast with item count
Don't
Do not list names of multiple items
Do not list names of multiple items

SAP Fiori Elements

If you are using SAP Fiori elements, remember to replace the “object” placeholder with your business object.

For more information, see SAP Fiori Elements – Mandatory Adjustments.

Do
Replace
Replace "object" with your specific business object
Don't
Do not leave the
Do not leave the "object" placeholder

Properties

You can change the values of the following properties. Only change the values if the standard values don’t work for your use case.

Position: We recommend that you always use the initial value (horizontally centered, at the bottom of the page).

Duration: The standard value is 3,000 ms. You can set a duration of more than 3,000 ms, but do not use less than 3,000 ms.

Width: The standard width is 15 em. You can extend the width, but do not use more than 35 em.

Offset: Do not change this value.

Auto-close: True/false

Example of a message toast
Example of a message toast

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

Gantt Chart

The Gantt chart enables you to present time-dependent data in an intuitive graphical manner, from a hierarchical and/or resource-oriented viewpoint. It shows the user the sequence in which various activities occur and the dependencies between these activities. The user can easily see the start and end of a particular activity.

The Gantt chart control provides the basis for creating such a Gantt chart and is a generic tool. Applications can consume the control in order to implement their use cases, and if necessary, they may even enhance the control.

It consists of three areas: a chart area, a table area, and a global toolbar.

Another feature is the option to have a split screen that includes two or more views next to one another, each view consisting of one table and one chart. These views can be arranged vertically or horizontally, and they share a common (global) toolbar.

Gantt chart control – Overview
Gantt chart control – Overview
Gantt chart control – Dual view
Gantt chart control – Dual view

Usage

Use the Gantt chart if:

  • You want to build an interactive and complex planning application involving activities, resources, hierarchical project structures, relationships, and other basic shapes such as diamonds, utilization line charts, or bar charts.
  • You want to build a simple application which may be read-only or which does not have a table component.
  • You want to build a simple application that is also capable of evolving into a more powerful application later on.

Do not use the Gantt chart if:

  • Your application needs to run on a smartphone. Consider using the planning calendar control instead.
  • You need to show less than 100 rows. You can still use a Gantt chart, but consider using the planning calendar control instead.
  • You want to show only a simple graphical representation based on rectangles (in other words, without relationships, milestones, and so on). Consider using the planning calendar control instead.

Responsiveness

The Gantt chart is responsive in principle. It can be displayed in a small window (size M) and preserve its layout without needing to create multiple levels of scrollbars nested in one another in the browser window. However, the control is not available in smartphone size (size S).

The Gantt chart control can be used to display data in tablet (size M).

Types

Like all SAP Fiori controls, the Gantt Chart is shown in compact mode on a desktop and in cozy mode on tablets.

For desktop devices, you can fit even more rows onto the screen by using the condensed mode together with the compact mode. This renders less white space for each item.

The condensed content density must always be set in addition to the compact mode. Do not use the condensed mode on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable or unwanted results, such as cozy-sized controls in condensed-sized containers, missing padding, and so on.

Note that neither compact mode nor condensed mode support touch interaction. Even on a desktop with a touch screen, users will have difficulty selecting rows or using controls inside the cells with their fingers.

Furthermore, condensed mode is not available for Internet Explorer 9. If you plan to use condensed mode, please provide a fallback.

For more information on cozy and compact modes, see content density.

Layout

The buttons contained in the optional global toolbar can control the behavior of the entire Gantt chart across multiple views. Each view can contain a local toolbar. This local toolbar is optional and is located above the tree table.

The buttons contained in the local toolbar can only control the behavior of its corresponding view. Each view can contain a tree table to the left and a chart to the right. However, the tree table is optional and the chart area can stand on its own.

Schematic visualization of the Gantt chart
Schematic visualization of the Gantt chart

Components

The Gantt chart consists of three areas: a global toolbar, a table area, and a chart area. There can be more than two table and chart areas in a split-screen layout.

Global Toolbar

The global toolbar provides standard functions, which are required by several applications. However, app teams can add extra functions. The user can also hide certain standard functions.

The following standard functions are available:

  • Legend (see details below)
  • Settings (see details below)
  • Zooming (see details below)
  • View combination switch: This dropdown menu is shown only if the consuming application provides more than one view combination.
  • View arrangement: Hide one of multiple views; add views; switch between vertical and horizontal alignment of the views. This can be skipped by the consuming application.
  • Overflow behavior: The global toolbar has the same overflow behavior as the SAPUI5 toolbars. For more information, see toolbar overview.
Gantt chart global toolbar
Gantt chart global toolbar

Legend

For the legend, we provide two templates to address fast implementation in most use cases:

  • List template: Displays a list of shapes and their corresponding texts. You can also add a checkbox before each shape, which allows the application to control if the shape will be displayed in the chart.
  • Dimension template: Shows a matrix of shapes and their corresponding texts for varied combinations of two dimensions.
List legend and dimension legend
List legend and dimension legend

Settings

Users can configure the display of the Gantt chart using the Change Settings button ( ). The control offers some standard settings (such as Indicate Current Time, Show Cursor Line, Show Divider Lines, Show Ad Hoc Lines, and Synchronize Time Scroll). The app team can also add their own settings to the settings dialog, giving users more options to control the behavior of the Gantt chart.

You can hide the Change Settings button if the settings are not suitable for your use case. The Gantt Chart control provides the API setToolbarSchemes, which allows applications to override the default buttons in the chart toolbar. Other APIs also allow you to define default values for all the settings. For more information, check out the API reference.

Standard settings
Standard settings

Zooming

The control provides a zooming function for the chart area. It consists of a Zoom In/Zoom Out magnifier buttons and a slider. You can hide the slider if there is not sufficient room for it, for example in size M. The zooming function also controls the labelling of the time axis, which determines whether you see years, months, or days. For more information, see time axis.

Show or hide the zooming slider
Show or hide the zooming slider

Chart Area

The chart area that includes the Gantt chart comprises a time axis and rows that contain different shapes. The position of a shape on the time axis depends on the dates of the object represented by the shape.

General

The chart area is closely connected to the table area. This means a line in the table corresponds to a line in the chart. Selecting a row in the table also selects this row in the chart. The height of the line is the same in both areas. If the user scrolls in one area, the other area scrolls in exactly the same manner.

Time Axis

The chart control can display the time axis in different time measurements as defined by the consuming application. Every time axis should have two levels. The app team can define the formatting of the labels for the times axis. The formats defined by SAPUI5 are supported. The Gantt control provides a default configuration for the time axis.

For more information, see time axis.

Time axis
Time axis
Example of possible timelines
Example of possible timelines

As shown in the above examples, you can display a vertical line indicating the current date. The actual date can be displayed on the axis. It’s also possible to show non-working time frames, such as weekends, by graying out these time frames. These dates can vary from line to line.

Basic Shapes

The Gantt control offers these basic shapes:

  • Rectangle
  • Polygon
  • Line (for example, to show notifications for rectangles)
  • Triangle (for example, to represent constraints such as time windows)
  • Diamond (for example, to represent milestones)
  • Chevron (for example, to represent project phases)
  • Cursor (for example, to represent checklist items)
  • Image (for example, to place images in the chart)
Basic shapes: rectangle, line, chevron, polygon, cursor, diamond, triangle
Basic shapes: rectangle, line, chevron, polygon, cursor, diamond, triangle

These shapes can also be combined. The chart control can render the shapes with different border and fill styles and border and fill colors, and use gradients. For more information, see colors.

App teams can add their own shapes, but they must adhere to the chart guidelines on colors. In general, you should use the qualitative palette, but if you need more colors, use the sequential palette.

When choosing the colors and hues to represent different object types, remember to select those that have a significant contrast.

The most commonly used shape is the rectangle (or bar).

Although it is technically feasible to use two bars above and below each other in one row, we do not recommend this practice. Particularly with high screen resolutions, this can lead to visual crowding so that the user cannot discern between different elements.

For example, if you want to show the degree of completion in a bar, it may be better to superimpose the finished section using a different shade over the original task.

Example of completion in a bar
Example of completion in a bar

Relationships

You can link two shapes with a line in various styles and colors. The exact meaning of the relationship depends on the use case and the application. However, it usually implies that one activity has to be performed or at least started before the subsequent activity can begin.

  • A relationship can begin from the start or end date of a shape.
  • A relationship can end at the start or end date of a shape.
  • The end of a relationship is shown using an arrow.
  • One shape can have multiple relationships.

The app team should define the logic of a relationship, such as rescheduling.

Relationship between shapes
Relationship between shapes

Utilization Chart

The utilization line chart and utilization bar chart enable you to display the level of consumed capacity of a resource at a specific point in time.

The system displays the utilization curve of the selected resource in the chart panel. You are notified of low load utilization and over-capacity by predefined colors. Moreover, the tooltip along the utilization curve displays the utilization of a resource in specific aspects according to your settings. You can customize it to fit your business needs, for example, to display the loading utilization of a vehicle resource in terms of volume or weight.

Example of utilization chart
Example of utilization chart

Recommendations

Use line widths large enough for the user to distinctly recognize the line. Avoid using dotted or dashed lines whenever possible.

Table Area

The Gantt control contains a table area that allows you to display and edit details of each line. For example, you may want to edit dates using a date picker rather than dragging a shape into the chart area. The table used in the control is the SAPUI5 tree table.

Behavior and Interaction

Various tooltips can be shown, but you should not use them to show additional information because users cannot access this functionality on touch devices.

The Gantt chart supports various events, allowing you to build rich and interactive applications.

Shape Selection

When a shape (including relationships) is clicked, the shape is highlighted and an event is raised. The application can provide respective event handling to catch the event and perform tasks as needed, such as showing an action sheet, or showing a detailed information popover. A parameter is provided to enable three different selection behaviors for different usage environments:

  • Single selection of the shape via clicking
  • Multi-selection of the shapes via clicking
  • Multi-selection of the shapes by pressing the Ctrl key and clicking
Multi-selection of shapes
Multi-selection of shapes

Shape Drag and Drop

When you click a shape and hold the mouse in the chart area, a shadow of the shape moves along the mouse. When you release the mouse, an event is raised, and then the application can provide an event handler to catch the event and perform tasks as needed, such as moving the shape to a new position. You can also drag and drop the shape across different views inside the same Gantt chart or even outside the Gantt chart; it’s also possible to drag-and-drop multiple selected shapes.

Shape drag and drop
Shape drag and drop

Shape Resize

When you move the mouse icon to a certain border of a shape, the mouse icon changes into a double-headed arrow, pointing left and right. This indicates that you can resize the shape. You can click and hold the mouse and then drag the shape border horizontally. Once the border reaches the expected position, release the mouse. The Gantt chart raises an event when the mouse is released. Your application can use an event handler to catch the event and then perform tasks as needed, such as changing the duration of the shape.

Resizing a shape
Resizing a shape

Relationship Creation

You can connect shapes in the Gantt chart. This can be used to represent the relationship between two activities.

To connect shapes:

  1. Click a shape to display its connection points on the shape borders.
  2. Click the connection point of the shape and then slightly drag it. This displays the connection points of all other connectable shapes.
  3. Connect the shape to another one by reaching its connection point via drag and drop.
Create a relationship
Create a relationship

Row Selection

You can select a row the same way as in a tree table, and the corresponding row in the tree table and chart part is highlighted;

Multi-row selection
Multi-row selection

Here are other important events supported by Gantt control:

  • Chart click
  • Chart right-click
  • Chart double-click
  • Chart mouse over
  • Horizontal scroll
  • Vertical scroll
  • Splitter resize

For more information, see the API reference.

Resources

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

Elements and Controls

Implementation

Busy Indicator

The busy indicator informs the user about an ongoing operation.

Busy indicator - Medium and Large
Busy indicator - Medium and Large
Busy indicator - Small
Busy indicator - Small

Usage

Use the busy indicator if:

The ongoing operation covers only part of a screen that has multiple controls, and:

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

Examples

  • File Upload: The file upload dialog contains multiple upload operations. The user must be able to cancel each operation. Since the operation is related only to one row and not to the full app, there is no need to block the whole screen. The user still needs to interact with the system, in this case to select the next file to be uploaded.
Example: Busy indicator for file upload
Example: Busy indicator for file upload
  • Table Rows: Each row in the table has an action related to the table item. Clicking the Run button in a specific row changes status of the current item. The user is still able to work on the other items or cancel the current operation.
    Since each SAPUI5 control provides a busy state by default, you could also set the busy state at row level. In this case, however, there would be no option to cancel the operation.
Example: Busy indicator in table rows
Example: Busy indicator in table rows

Do not use the busy indicator if:

  • The operation takes less than one second.
  • You need to block the screen because the user is not supposed to start another activity. In this case, use the busy dialog.

Components

The busy indicator is a blue circle and can also display a text description.

Busy indicator text
Busy indicator text

Guidelines

  • Do not change the mouse cursor to indicate the ongoing operation.
  • Do not use a custom progress indicator icon.
  • Try to avoid showing multiple busy indicators at once.

Properties

The size of the busy indicator can also be changed.

Busy indicator sizes
Busy indicator sizes

Resources

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

Elements and Controls

Implementation

Smart Table

Intro

The smart table creates a responsive table, grid table, tree table, or analytical table based on an OData (Open Data Protocol) service and its annotations. The table toolbar comes with additional built-in features, such as personalization, export to spreadsheet, and variant management.

When to Use

Use the smart table if:

  • You use an OData service for your app (OData version 2 only).
  • The feature set of the smart table fits for your app. In this case, the smart table is faster to implement.
  • You need more than one of the major features of the smart table. Otherwise, you might not benefit from a shorter implementation time. For example, if you just need the export to spreadsheet feature, creating a responsive table directly is usually faster than using the smart table.

Do not use the smart table if:

  • You use a different technology to OData version 2. Use the corresponding table control directly.
  • You need more flexibility in the content design, such as several different row templates or less complex personalization features. Use the responsive table directly.
  • You do not have complex data. Another control like a select, combo box, list, grid list, tree, or smart list might do the job better.
  • You have very complex data. Did you check the chart?
  • Users need to switch between a chart and table. The smart table is not designed to work inside an existing chart container. In this case, use either the smart chart or the corresponding table directly.
  • You need to layout different controls in a table-like grid. Use a flexible grid instead.
  • You need to layout different input fields with labels. Use a form, simple form, or smart form.

Components

The smart table consists of a table toolbar (1), an infobar (2), and a table (3).

The components of a smart table
The components of a smart table

Table Toolbar

Toolbar with all features provided by the smart table out-of-the-box
Toolbar with all features provided by the smart table out-of-the-box

The table toolbar is generated automatically. The following toolbar content is provided by the smart table out-of-the box:

  1. Title
  2. Item counter
  3. Variant management
  4. Show Details / Hide Details
  5. View Settings
  6. Export to Spreadsheet
  7. Maximize / Minimize

In addition, you can add app-specific actions.

Title

The title is optional (property: header).

Guidelines
Add a title whenever the title is not indicated in the surrounding area.
Developer Hint
If you don’t provide a title, ensure that you support screen reader users: create a simple table in the XML view, use ariaLabelledBy to point to the corresponding text, and add this table to the smart table. Make sure that the table type within the smart table is set accordingly. The smart table will take care of the rest (creating columns, and so on).

Item Counter

The item counter is optional and only available if you show a title (property: showRowCount).

Guidelines
Show the item counter together with the table title, unless:

Variant Management

Variant management is optional (properties: persistencyKey, useVariantManagement, currentVariantID, association: smartVariant).

Guidelines
Use variant management only if really needed.

Show Details / Hide Details

Show Details / Hide Details is mandatory with and only available for the responsive table. Columns with a low priority (low or medium priority on phones) are hidden in the pop-in area (properties: demandPopin, showDetailsButton, annotation: UI.Importance). You can define which column priority levels are hidden (property: detailsButtonSettings). The button only appears if there are corresponding columns in the pop-in area.

Details hidden
Details hidden
Details shown
Details shown

View Settings

View Settings are optional. The button triggers a P13n Dialog (property: useTablePersonalisation). The View Settings dialog can also be opened with the shortcut Ctrl+Comma.

Guidelines
Offer view settings only if they are really needed. Tables with just a few columns and rows do not need to be sorted, filtered, or grouped.

Sort and Filter

Sorting, filtering, and column settings are automatically available for all columns in all tables. For single columns, you can remove the sort and filter settings (annotations: SortRestrictions, FilterRestrictions).

  • The current sort state and sort order is displayed as an icon in the column header of the sorted columns.
  • The current filter state is displayed as follows:
    • In the responsive table, an infobar is shown if filters have been set in the table personalization settings.
    • For all other tables, filtering is indicated by an icon in the column header of each filtered column.

When amounts with different currencies appear in a single column, you can change the sort behavior to sort these columns first by currency, then by amount (annotation: ApplyMulitUnitBehaviorForSortingAndFiltering). This behavior is applied for all such columns in the smart table. It cannot be defined per column.

Guidelines

  • Do not turn off the info bar (property: useInfoBar).
  • In the default delivery, sort items in a meaningful order. This works only for the grid table, tree table, and analytical table. You can also provide default filter settings (all tables) and grouping (responsive table and analytical table only) (annotation:
    PresentationVariant).
  • If the smart table is used together with a filter bar (property:
    smartFilterId), do not offer filtering for the smart table itself.

Developer Hint
The smart table can be linked to a smart filter bar. If linked, the filter bar settings are automatically applied to the smart table (sap.ui.comp.smarttable,SmartTable, property: smartFilterId).

Group

Group settings are only available for the responsive table (all columns, one level only) and the analytical table (dimension columns only, multiple levels).

The following text is usually shown on the group header:
[Label of the grouped column]: [Grouping value]

Within the analytical table, the grouped column remains visible by default if it is grouped using the P13n Dialog. The column is hidden if it is grouped using the column header menu.

Guidelines
In some cases, the group header text may not be shown automatically as described. This applies to special cases in the analytical table (for example, if the displayed text is not taken directly from the data source), as well as custom columns in both responsive and analytical tables. In such cases, you must set and format the group header text yourself.

Column Settings

Column settings are used to show and hide columns. For the grid table, tree table, and analytical table, the column settings automatically enable resizing via the column header and size-to-fit for text-only columns (double-click on column separator line).

Guidelines
If sorting, grouping, and/or filtering are needed, also show the column settings (sap.ui.comp.smarttable.SmartTable, property: useTablePersonalisation).
Developer Hint
Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

Export to Spreadsheet

Export to Spreadsheet is optional. The button triggers either a front-end export using the export to spreadsheet utility, or a back-end export via Gateway (properties: useExportToExcel, exportType). The front-end export allows for additional settings and can also be triggered with the shortcut Ctrl+Shift+E.

Guidelines

  • Only offer the Export to Spreadsheet option if your end users typically export the data shown in the table 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, tables with only a few items, shopping carts, or data that does not need to be analyzed.
  • If you offer the Export to Spreadsheet button, use the front-end export.
  • If your table has columns with non-textual content, provide a textual equivalent for those columns. Non-textual content is not exported.

Warning
With both methods, the file size is limited by the available browser memory. As a result, exporting large tables can lead to memory overflows and crash the export process.

Apply the following size restrictions as a rule-of-thumb:

  • For the front-end export, do not export more than 2 million table cells on desktop browsers or 100,000 table cells on tablets and phones.
  • For the back-end export, do not export more than 100,000 table cells.

For larger tables, consider using custom-built, specialized export solutions instead.

Maximize / Minimize

Maximize / Minimize is optional. It allows users to show the table in full screen mode and to exit full screen mode (property: showFullScreenButton).

Guidelines

App-Specific Actions

App-specific actions can only be added using a custom toolbar (aggregation: customToolbar).

Developer Hint

Infobar

Infobar with filter information
Infobar with filter information

The infobar is only available for the responsive table. It indicates which filter settings are currently active. If no filters are set, the infobar is hidden (property: useInfoToolbar, value: Auto).

Guidelines

Table

Responsive table within a smart table
Responsive table within a smart table

The table is generated automatically. The sections below describe the behavior and different possibilities:

Table

The table provides the following features:

Guidelines

  • Use the responsive table wherever possible. Use the other table types only if really needed. If you use another table, provide a fallback solution for phones.
  • For the responsive table, the smart table initially loads 20 items and shows a More button for loading additional items. Change this behavior if:
    • You expect fewer than 200 items. Load all items from the start (sap.m.Table, property: growing).
    • You expect more than 200 items. Adapt the number of items initially loaded to cater for large screens, and load additional items automatically when the user scrolls down (sap.m.Table, property: growingScrolllToLoad).

Developer Hint
To change the growing behavior, create a responsive table with just the settings for the growing behavior, and hand it over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on).
Developer Hint

  • The property tableBindingPath defines the path from which the data is fetched.
  • The property enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

Developer Hint
To change the selection mode, add a navigation indicator to single rows, or add a highlight to specific rows, you need to create a table with the corresponding settings. You do not need to define anything else. Hand this table over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on). This method allows you to use the multi-selection plug-in with the grid table, tree table, and analytical table.

Column Visibility

  • Columns are created automatically. Items are rendered based on the properties and metadata of the underlying OData service (annotation: LineItem, properties: entitySet, tableBindingPath, initiallyVisibleFields, ignoreFields). A column is generated for each OData entity property.
Developer Hint
If a column needs to be in the model but should not be shown, you can hide it from both the table and the P13n dialog (property: ignoredFields, annotation: UI.Hidden).

Use this option if:

  • A column is needed to provide an ID that is used for navigation purposes only. However, you only want to display the corresponding text on the UI, and not the ID.
  • The values of a column are needed to perform calculations, but only the results are shown on the UI.

You can use the property requestAtLeastFields to request additional (technical) columns with every request, regardless of whether these columns are currently visible. This does not work with the analytical table.

The property ignoreFromPersonalization is only available with the analytical table. It loads additional key fields that are needed for aggregations but are never visible.

Developer Hint
Columns can be removed at runtime. This is useful if the same table is used for similar, but slightly different objects. For one of the objects, specific columns need to be shown, for others they must be hidden, and users must not be able to add them in the personalization settings (function: deactivateColumn).
  • You can define which columns are initially visible when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleFields).
Guidelines

  • Keep the number of initially visible columns to a minimum. Avoid pop-in behavior (responsive table) or horizontal scrolling (all other tables) on a tablet screen size in the default delivery (annotation: PresentationVariant/ LineItem).
  • Also keep the number of additional columns offered in the personalization settings to a minimum. You can use the P13n dialog to let users 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 each column that is initially visible, the LineItem annotation includes a DataField record, which allows you to influence the content rendering of the smart table.
    For columns that are initially invisible, the content rendering can also be influenced via the annotation DataFieldDefault.
Developer Hint
If the same column is defined via LineItem and via DataFieldDefault, LineItem wins.

Column Layout

  • A default column width can be calculated for each column based on the data type, the column label, the edit/read-only state, and the annotations: textArrangement, MaxLength for strings, Precision and Scale for numeric data (property: enableAutoColumnWidth).
    The calculated width is between 3 rem and 20 rem. Apps can change this default width if needed (annotation: CSSDefaults).
    If the combined width of all the columns is less than the width of the table, the remaining space stays empty.
Guidelines
Choose a column width that avoids truncation for the initial data and (if feasible) for the column header label. If the default column width doesn’t fit, change it.
Developer Hint
For the responsive table, enableAutoColumnWidth also applies the following changes:

  • The smart table property demandPopin is set to true.
  • The responsive table property fixedLayout is set to Strict.
  • The responsive table property contextualWidth is set to Auto.
  • Column resizing is enabled for all columns (including custom columns).
  • Labels in the column headers no longer wrap. If there is not enough space, they truncate.

In this case, the properties above must not be managed by the app.

Responsive table with automatically calculated column widths, resizing, and remaining space
Responsive table with automatically calculated column widths, resizing, and remaining space
  • If the automatically generated content does not fit for your use case, you can override the automatic behavior with your own column template.
    You can also add further columns. This allows you to provide columns with app-specific or inline actions, columns which show calculated values (based on more than one OData entity property), or – for responsive tables – columns that show more than one control.
Developer Hint
To add or override columns (“custom columns”):

  • Use an XML view to define the underlying table with just the columns to be added/overridden.
  • To override columns, provide the column key of the column you want to exchange.
  • Add this “unfinished” table to the smart table. The smart table adds all the automatically generated columns and additional features.

Make sure that the sortProperty and the filterProperty are set (define p13nData via the aggregation CustomData). If you offer the export to spreadsheet option,  ensure that it works as expected.

If you are using a responsive table, also make sure that the responsive behavior for this column works as expected (sap.m.Column, property: importance).

Column Headers

  • You can specify a column header text for each column (annotation: sap:label).
Guidelines
Provide a column header text for each column. (annotation: sap:label).
  • The column headers contain the following settings:
    • Sort Ascending, Sort Descending
    • Filter: Opens the P13n Dialog. If this does not fit for your use case, exchange this menu item (property: enableCustomFilter)
    • Group (only analytical table, only on dimension columns)
    • Total (only analytical table, only on measure columns): This setting is not persisted (annotation: sap:aggregation-role, value: measure).
      If a column contains entries with different units of measurement, a Show Details link appears instead of the total. Clicking the link opens a popover showing the subtotals per unit of measurement.
    • Freeze (only available for grid table, tree table, and analytical table): Must be added manually.
Guidelines
Offer column totals by default for all columns where totals make sense (annotation: PresentationVariant).
Developer Hint
To add a Freeze option manually, declare the corresponding table inside the smart table in the XML view, and use the corresponding settings for this inner table.

Clicking the column header reveals sort and filter options (responsive table)

  • Smart Table - Column Header - 1.90
Column header menu for a dimension column of an analytical table within a smart table
Column header menu for a dimension column of an analytical table within a smart table
Column header menu for a measure column of an analytical table within a smart table
Column header menu for a measure column of an analytical table within a smart table

Content

The smart table offers the following options for creating columns automatically:

  1. You can render the smart table in either read-only or edit mode (with no option to switch), or allow users to switch between the two modes (properties: editable, useSmartToggle).
  2. In read-only or edit mode, the smart table renders the controls as listed in the table below, or uses the smart field for both modes. If you use smart fields together with the option to switch between read-only and edit mode, the smart table renders the read-only controls as in the list below, but uses the smart field for edit mode. The smart field limits the rendering options (aggregation: customData, key: useSmartField), but also allows for:
    • Better control of the visibility of a field per row (smart field, annotation: FieldControl)
    • Use of value help for input fields
Developer Hint
From a performance perspective, using the smart field is more expensive than using the controls provided by the smart table directly. With this in mind, follow the rules below:

  • For read-only tables, use the controls provided by the smart table.
  • For simple editing cases with no need for FieldControl or value help on input fields, use the controls provided by the smart table.
  • For more complex editing cases, use smart fields.
  • For switching between read-only and edit modes:
    • In read-only mode, use the controls provided by the smart table.
    • In edit mode, use either smart fields or the controls provided by the smart table, based on the guidance above.

In cases where the controls are rendered by the smart table, the following controls are used:

Read-only Edit Annotations / Edm type Comment
Static text Text Input field Edm.String
Decimal numbers Text Input field Precision, Scale, Edm.Byte, Edm.Decimal, Edm.Double, Edm.Int16, Edm.Int32, Edm.Int64, Edm.SByte, Edm.Single
Status information Object status or Icon Input field Criticality, CriticalityType,
CriticalityRepresentationType		 Do not use editable status information.
Key identifier Object identifier (responsive table)
Text
(all other tables)		 Input field for the ID SemanticKey,
Common.EditableFieldFor
Text and ID Text, object status, or object identifier Input field for the ID TextArrangement Use together with the annotation mentioned above for static text, status information, or key identifier.

Sorting, filtering, and grouping only works for the ID, even if the ID is not displayed.
Links with/without quick view Smart link Smart link SemanticObject Smart links can be customized using the aggregation: semanticObjectController
Dates Text Date picker Edm.DateTime, sap:display-format, value: date, IsCalendarDate
Dates and times Text Date/time picker Edm.DateTime, Edm.DateTimeOffset
Times Text Time picker Edm.Time
Fiscal periods Text Input field IsFiscalYear, IsFiscalPeriod, IsFiscalYearPeriod, IsFiscalQuarter, IsFiscalYearQuarter, IsFiscalWeek, IsFiscalYearWeek, IsDayOfFiscalYear
Amounts with currencies Two text controls Input field for the amount sap:semantics, value: currency-code In edit mode, the currency is shown as static text next to the input field.
Phone numbers Link Input field IsPhoneNumber Opens the system application for making phone calls.
Email Link Input field IsEmailAddress Opens the system application for writing emails.
Pictures Image Input field IsImageURL Only available for the responsive table. In edit mode, the input field contains the URL to the image.
Boolean Text Checkbox Edm.Boolean For read-only, the displayed text is Yes or No.

In all cases, the smart table automatically takes care of the content alignment and formatting (except for custom columns).

Input fields can be accompanied by a value help dialog (annotation: ValueList). If annotated, triggering the value help button opens a value help dialog. Within this dialog, you can provide a search field (annotation: ValueList, property: SearchSupported).

If no ValueList annotation is provided, you can restrict the number of characters for an input field (annotation: MaxLength).

You can provide additional controls, such as micro charts, rating indicators, progress indicators, and buttons, as custom columns (using an XML view). For custom columns, you must provide any read-only and editable content manually.

Guidelines
For inline actions, use a text-only or an icon-only button. Make sure the icon communicates the function clearly enough. Otherwise, use a text-only button.

If the smart table is used with the responsive table, you can show the status of an item by displaying a highlight indicator on the left of the item (property: highlight).

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, export to spreadsheet, 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.

Empty Tables

If there is no data to show, the smart table renders a default text. This text can be overwritten by the app development team. The default texts are:

  • If a table is initially empty:
    No items available.
    Overwrite this whenever a hint can be provided on how to fill the table with data.
    (property: initialNoDataText, value: $NO_FILTERBAR)
  • 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.
    (property: initialNoDataText, value: $FILTERBAR)
  • 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.
    (aggregation: noData, changeable at runtime)
  • If the user has hidden all of the columns in the personalization settings, the following text is shown:
    Right now, there are no visible columns in the table. Please select the columns you need in the table settings.
    This text cannot be changed.
Guidelines

  • For all other cases, provide instructions on how to fill the table with data (aggregation: noData).
  • The “no data” text can be exchanged at runtime. Use specific texts for different situations.
  • Avoid displaying a table without any items, especially when the app is initially loaded.

An empty smart table
An empty smart table

Errors and Warnings

To indicate that the table contains items with errors or warnings, the smart table can show a message strip above the table (aggregation: dataStateIndicator). On the message strip, information about errors or warnings is provided, as well as the possibility to filter down the table to the corresponding rows. When issues are solved or when new issues appear, the message strip is updated accordingly.

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

Table containing warnings
Table containing warnings
Table containing errors and warnings
Table containing errors and warnings
Guidelines
To show that an item contains an error,

Developer Hint
Binding-related messages are shown automatically.

Responsiveness

The smart table acts exactly like the embedded controls. For details see:

  • Toolbar Overview
  • Infobar
  • Responsive Table via auto pop-in mode
    (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true).
    You can use the UI.Importance annotation to influence the priority of each column.
    You can provide a Show Details button to let users show/hide columns with low importance (property: showDetailsButton).
  • Grid Table, Tree Table, Analytical Table:
    These controls are not intended for use on smartphones. If you use a smart table with this configuration, ensure that you implement a fallback solution for small screens.
Guidelines
If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true). Ensure that the most important columns stay in the tabular layout as long as possible (annotation: UI.Importance). 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.

Developer Hint

  • To change the layout of the pop-in area (Block, GridSmall, GridLarge), you need to create a responsive table with the corresponding settings (property: popinLayout). You do not need to define anything else. Hand this responsive table over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on).
  • Do not use the annotation UI.Importance together with the grid table, tree table, or analytical table. It hides columns with low priority on phones or narrow-width screens, without the possibility to show them again.

Examples

Responsive table within a smart table
Responsive table within a smart table
Grid table within a smart table
Grid table within a smart table

Top Tips

  • If you are using the responsive table, enable and configure the auto pop-in mode and use the Show Details / Hide Details button.
  • For custom columns, follow the guidelines of the respective table. If needed, use responsive paddings for aligning the content.
  • Enable only the features that are needed for your use case. Very small tables do not need to be sorted, filtered, grouped, and rarely exported. Don’t just add unnecessary features for consistency purposes.
  • If the page has a filter bar, don’t offer filtering for the table.
  • If you are using custom columns, make sure that any export and personalization features you are using also work for these columns.

Properties

The following properties are available for sap.ui.comp.smarttable.SmartTable:

  • The property: toolbarStyleClass is deprecated. Do not use it.
  • The property: useOnlyOneSolidToolbar is deprecated. Do not use it.

Related Links

Elements and Controls

Implementation

Smart Link

Intro

Like the quick view, the smart link triggers a popover from a text link. This popover shows additional information, such as simple object details, and offers links to related apps for the user to take action. The user can choose which links are shown in the popover by selecting them in a separate dialog.
The smart link is a smart control that uses metadata annotations to offer user-specific navigation. It analyzes the user’s assigned apps and offers only relevant navigation targets.

When to Use

Use the smart link if:

You want to offer direct navigation to a related app. For example:

  • Navigate from a product list to the app for changing the pricing
  • Navigate from a sales order list to the app that shows a customer’s balance

You want to show a popover with contextual information or navigation. For example:

  • Offer navigation to multiple related apps
  • Display simple object details

Do not use the smart link if:

  • You want to display more or complex information about an object. Use the object page or charts instead.
  • Access to metadata is not possible, and only a direct link to a website, document or application is needed. Use the standard link instead.
  • You need to structure information in a deeper hierarchy. Use the quick view or a list drilldown instead.

Components

The smart link popover contains the following areas:

  1. The header bar of the smart link popover is only visible on mobile devices (see example image for responsiveness, size S).
  2. The title area contains a title and a subtitle. You can also show the title as a link, which can be used to navigate to the corresponding object or fact sheet. You can use the subtitle to show an object ID, for example.
  3. The content area shows object-related information, such as details about a product or contact information. You can use any UI control, based on what best fits your use case.
  4. The link area offers links to all other apps that are relevant for a user role. The link list includes all semantic objects defined for the app, and can also include additional links defined manually by the application development team. The link area can have two states:

Link area is empty:
If no links have been selected for the app, or if there are more than 10 links, the link area is initially empty. Instead, the user sees a Define Links button, which opens a dialog for selecting the links to be shown.

Links are shown:
As soon as the link area contains links, the button text changes to More Links. This opens the same selection dialog.

Only the header bar is mandatory (for mobile devices). All the other sections are optional. For example, you might choose to show only a content area or a only a link area, depending on your use case.

The areas of the smart link (header bar not shown)
The areas of the smart link (header bar not shown)

Behavior and Interaction

The smart link and its popover are always triggered by clicking a text element that appears as a link. You can place this text element in any list, table, or other container. You can also set the link label individually. Clicking outside the popover closes it. If only one link is offered, and there is no additional information, the smart link control navigates directly to the target without opening the popover.

If the semantic object annotation is not set, the smart link is rendered as sap.m.Text by default. However, you can also opt to render any other control.

Link Selection Dialog

Clicking the More Links or Define Links button opens the Define Link List dialog. There, the user can select the app links to be displayed in the link area. The links offered in the selection list are modifiable semantic objects suggested by the smart link control. The app team can remove links from the selection list, change the link texts, or manually add links to any website or app.

Exception: Within SAP Fiori elements, the links offered in the Define Link List dialog are generated automatically. App teams cannot adapt the list.

You can switch off the More Links / Define Links option by setting the property enableAvailableActionsPersonalization to “false”. By default, it is set to “true”.

Smart Links in a Smart Table

Within a smart table, the link label of the smart link is set automatically using the semantic object annotation. In other words, you can’t change the description. If there are no navigation targets, the smart link is rendered as sap.m.Text.

Define link list dialog with a list of application links
Define link list dialog with a list of application links

Responsiveness

The responsiveness of the smart link is based on the responsiveness of the popover that overlays the content.

On desktop devices, clicking anywhere outside the popover closes it.

On mobile devices, the smart link opens a full screen dialog with a Close icon ( ) on the top right.

Size S – On smartphones, the smart link overlays the content
Size S – On smartphones, the smart link overlays the content
Sizes M/L/XL - Smart link shown in a table on a desktop device
Sizes M/L/XL - Smart link shown in a table on a desktop device

Top Tips

  • Check the related apps you offer carefully. Only display those that are relevant for the user.
  • Use meaningful link names in the link area. Do not use the same link name more than once. If necessary, rename the links to suit your context (for example, “Add Product” instead of “Manage Products”).

Related Links

Elements and Controls

Implementation

Time Picker

The time picker allows the user to select a localized time. It can be used with touch, mouse, or keyboard input.

When to Use

Use the time picker if:

  • Users need to select a time.
  • Users need to select a time range. In this case, one time picker can be used to set the starting time and a second one to set the end time.

Do not use the time picker if:

  • Users need to select a specific duration, such as 1 minute and 30 seconds.
  • Users need to select a standard duration such as 15 minutes, 30 minutes, 1 hour, or 2 hours. In this case, use the select control instead.
Time picker
Time picker

Components

The time picker consists of a time input field (1). Users can enter a time directly or use the time picker button (2) to select a time using the time picker popover (3).

On mobile and tablet devices, selecting the time input field opens a time input popover (A) for entering the time with the touch keyboard.

The time input field can also contain a placeholder (input prompt).

Time input field on desktop
Time input field on desktop
Time picker popover on desktop
Time picker popover on desktop
Time input field on tablet
Time input field on tablet
Time picker popover on tablet
Time picker popover on tablet
Time input field on phone
Time input field on phone
Time input popover on phone
Time input popover on phone
Time picker popover on phone, opened in full-screen
Time picker popover on phone, opened in full-screen

Time Picker Popover

In the time picker popover, the user can select a time by using the clock face to set hours, minutes, and seconds.

The full time is always displayed at the top of the popover.

If the user has opted for the 12-hour format in the user settings, an AM/PM switch is also displayed.

If seconds are not relevant for the use case, you can remove the seconds field.

Components of the time picker popover
Components of the time picker popover

Hours Clock Face

Depending on the time format, the hours clock face shows 12 hours or 24 hours:

  • The 12-hour clock face shows only one circle.
  • The 24-hour clock face shows an additional inner circle for the times from 13:00 to 24:00 hours.
    24-hour clock face
    24-hour clock face

    Minutes Clock Face

    When the minutes value is selected in the time display, the minutes clock face is shown.

    Minutes clock face
    Minutes clock face

    Seconds Clock Face

    When the seconds value is selected in the time display, the seconds clock face is shown.

    Seconds clock face
    Seconds clock face

    Behavior and Interaction

    Users can enter the time in two ways:

    • Enter a time directly in the input field
    • Select a time using the time picker popover

    Entering a Time in the Input Field

    On desktop devices, the user selects the time input field and enters the time using the keyboard.

    Entering a time directly
    Entering a time directly

    On tablet and mobile devices, selecting the time input field opens a time input popover. The user can then use the mobile keyboard to enter the time. For the 12-hour time format, the popover also offers an AM/PM switch.

    1) Focus on time input field
    1) Focus on time input field
    2a) Time input popover, 24-hour format
    2a) Time input popover, 24-hour format
    2b) Time input popover, 12-hour format with AM/PM switch
    2b) Time input popover, 12-hour format with AM/PM switch

    Selecting a Time with the Time Picker Popover

    By default, the time picker shows the hours clock face, and the hour value is highlighted in the time display at the top of the popover. On desktop devices, users can select the hour using a mouse or the keyboard arrows. Tablet and mobile device users can drag the handle around the dial to the desired number, or tap the number on the dial. The selected hour is then entered in the time display at the top.

    When an hour value is set, the hours clock face automatically switches to the minutes view: the minutes clock face is shown and the minutes value is highlighted in the time display. If an hour was selected by mistake, the user can switch back to the hours clock face by selecting the hours value.

    Minutes and seconds are selected in the same way.

    Clicking the OK button confirms the selected time. Clicking Cancel or clicking anywhere outside the popover discards the changes.

    Selecting time on a desktop device
    Selecting time on a desktop device
    Interaction options on mobile devices: Drag or tap
    Interaction options on mobile devices: Drag or tap

    Default Time

    You can set a predefined time, which shows as the initial value in the time input field and the time picker popover. If you don’t set a default time at application level, the control defaults to the current time. Users can overwrite the initial value.

     

    Preventing Errors

    You can prevent users from making incorrect entries by only allowing certain characters (see mask input). If the user enters a time that has the correct format but is invalid (such as 12:60:85), the time picker displays a validation error (see input validation).

    You can switch off the integrated mask input feature, but we strongly recommend using it. Only deactivate mask input if you need to make an exception for your use case (for example, if a variable length is required for a specific locale).

    Style

    The time picker has five basic value states:

    1. Regular
    2. Information
    3. Success
    4. Warning
    5. Error

    For the information, warning, and error states, you can also display a message with additional information below the field.

    Time picker value states
    Time picker value states

    Responsiveness

    The time picker comes with a cozy mode and a compact mode. In the compact mode, the time input field and the button are smaller than in the cozy mode. For more information, see Content Density.

    For mobile (size S) devices, the time picker popover does not open below the time input field, but in a subview.

    Time picker on a desktop device
    Time picker on a desktop device
    Time picker on mobile (size S)
    Time picker on mobile (size S)

    Guidelines

    Time Formats

    Seconds

    Only let the user select time in seconds if this information is really necessary.

    Time Zone

    If the user has to set a time that is time zone-sensitive, offer a select control next to the time picker control to choose the appropriate time zone.

    For more information, see Formatting Time.

    Properties

    AM and PM are locale-dependent. You can set the locale with the property localeId.

    You can define the display format for the time in the input field and at the top of the time picker popover (property: displayFormat). For more information about time formats, see Formatting Dates.

    Related Links

    Elements and Controls

    Implementation

    Calendar Card

    Information
    The calendar card is already available in SAPUI5, but cannot currently be consumed in the SAP S/4HANA environments (on premise and cloud).

    Intro

    The calendar card is an interactive calendar for a single entity, such as a person. It shows a chronological list of appointments for the selected date.

    The calendar card is an integration card that uses the generic structure of the sap.f.card control.

    When to Use

    You can use the calendar card to show a calendar for one person, based on the single planning calendar.

    Do not use it to show multiple appointments/calendars. Use the planning calendar instead.

    Components



    1. Header: Basic information about the calendar card, including the title, subtitle, and appointment counter.

    You can define a navigation target for the header area (recommended). This is typically the underlying application containing the full calendar.

    1. Calendar title: Title set by the application team. Use a title that reflects the use of the calendar in your application context.
    1. Calendar subtitle: Subtitle set by the application team to further qualify the focus of the calendar.
    1. Counter: Indicates how many appointments are displayed on the card and how many exist for the selected day overall.
    1. Calendar navigation: Users can navigate to the previous/next period (for example previous/next month) or use the picker to select the month and year directly.
    1. Calendar with interactive days: Interactive calendar, showing the selected day, current day, and special days.
    1. Legend: In-place legend. You can specify the number of items that are shown. The More (x) text indicates how many legend items are hidden.

    The different types of legend items are indicated by different shapes: Squares refer to highlighted days, circles refer to types of appointment.

    Group titles from the planning calendar legend are not shown in the calendar card.

    1. Appointment list: Shows appointments for the selected day. You can define the number of visible appointments.
    1. Appointment duration: Indicates the duration using a dynamic combination of start date, duration, and end date. The format is determined automatically based on the user’s locale.
    1. Appointment: The appointment can have an icon, a title, and a subtitle.

    The appointment title and subtitle do not wrap. If there is insufficient space on the card, the text is truncated.

    1. Indicator for more appointments: The More button indicates that additional appointments exist for the selected day.

    You can define a navigation target for the button (recommended). This is typically the detail app containing all the appointments.

    Guidelines

    • Define a suitable navigation target for the header area.
    • To give users easy access to the full list of appointments, define a suitable navigation target for the More button at the end of the appointment list.
    • To keep the calendar card simple, display only the most important legend items.

    Components of a calendar card
    Components of a calendar card

    Behavior and Interaction

    Calendar Card Header

    When a day is selected, the counter adapts to show the number of appointments for that day (visible appointments/total appointments).

    If a navigation target has been defined, clicking the navigation header opens the corresponding application.

    Selecting a Date

    Instead of offering a date picker in a popover, the calendar card changes views in place and allows the user to drill in.

    At each level, the user can select the relevant period, navigate back and forth using the Previous and Next arrows, or drill down to the next level using the date picker.

    Drill-
    down
    Level    		 View Selection Previous/Next Arrows Date Picker Display View Opened by Date Picker Link
    1 Days in the month Day Previous month, next month Selected month and year Months in the selected year
    2 Months in the year Month Previous year, next year Selected year Years in a year interval
    3 Years in a year interval Year Previous year interval, next year interval Selected year interval Set of year intervals
    4 Set of year intervals Year interval Previous set of year intervals, next set of year intervals n/a n/a
    Calendar card - Picker views
    Calendar card - Picker views

    Appointment List

    When a day is selected, the appointment list adapts to show the appointments for that day.

    If a navigation target has been set for the appointment, clicking the appointment navigates to the corresponding application (one click area).

    If additional appointments exist, and a navigation target has been defined, clicking More opens the corresponding application.

    Responsiveness

    The responsive behavior of the calendar card depends on the container control of the host environment (for example, SAP Fiori launchpad). The size of the card adapts dynamically to the size of the container.

    Width

    Calendar cards adapt to the available width. If the width exceeds 589 px, the card switches automatically from a 1-column layout to a 2-column layout.

    Width Layout
    295 px (minimum width) 1 column
    295 – 589 px 1 column
    > 589 px 2 columns

    You configure the width of the calendar card by specifying the number of grid columns. The width of the card (and thus the breakpoint for the 2-column layout) is then determined by the grid.

    1-column layout - wider card shows more legend items
    1-column layout - wider card shows more legend items
    Guidelines
    When defining the number of grid columns for your calendar card:

    • Ensure a minimum width of 295 px (minimum size for the calendar).
    • To enable the two column layout on larger screens (recommended), allow more than 589 px.

    1-column layout and corresponding 2-column layout showing more appointments
    1-column layout and corresponding 2-column layout showing more appointments

    Height

    The height of the calendar card is determined by the content (no scrolling possible). It depends on the number of appointments that exist for the selected day and the maximum number of visible appointments you have defined.

    When the width exceeds 589px and the card rearranges into two columns, and the height of the card shrinks. The minimum number of rows is determined by the number of visible appointments.

    Note: If the calendar card snaps to the grid row (depending on overall card snapping behavior), this will sometimes result in blank space in the card.

    Guidelines
    To prevent the card from becoming too tall, show only a reasonable number of appointments.

    Top Tips

    • Keep the legend as simple as possible.
    • Consider the height of the card when you define the number of visible appointments.

    Related Links

    Elements and Controls

    Implementation

    Calendar Card (card explorer)

    Using Tooltips

    Tooltips appear next to the mouse pointer when it hovers over an element that offers a tooltip. Tooltips are shown only for elements that do not have a label or, in rare cases, to display additional information.

    Since tooltips are handled by the browser, the form of tooltips depends on the platform, the browser, and the version.

    Usage

    Use a tooltip if:

    • You have an element that cannot be attached to a label.
    • You are showing an icon-only button.
    • You want to show in-place information within a map.
    • You are showing a button that contains only an icon and a number.

    Do not use a tooltip if:

    • You want to show the full text for a truncated item. Instead, make more space for the item.
    • Text is truncated on a control that doesn’t support wrapping. Instead, show the full content with one click in a popup. See Wrapping and Truncating Text.
    • You don’t want to use a label. You should always use a label.
    • You want to offer an explanation or provide help. Instead, use the Web Assistant.
    • The content of the tooltip would be redundant.

    Responsiveness

    Tooltips are usually invoked by a mouseover event, which is why they are limited to desktop devices. Most touch-only devices have no way of showing tooltips.

    Because tooltips cannot be displayed on all devices, they should never contain critical information. They should also not contain redundant information.

    Types

    Icon-Only Buttons

    Icon-only buttons must have a tooltip to indicate the action the button will trigger.

    .

    Icon-Only Buttons with Amounts

    Icon-only buttons that contain numbers, but no text, must also have a tooltip.

    Maps

    Within maps, different areas and hotspots can show different tooltips to elaborate the current position.

    • Hovering over a map
    • Not hovering over a map

    Guidelines

    Overwriting standard icon tooltips

    The icon within an icon-only button usually comes with a standard tooltip. However, this default tooltip contains the technical icon name, which may not be the right term for the icon in your context. Always check all icons, and overwrite the default tooltip texts with suitable texts for your specific use case.

    Do
    Icon with app-specific tooltip (default overwritten)
    Icon with app-specific tooltip (default overwritten)
    Don't
    Icon with standard tooltip (default)
    Icon with standard tooltip (default)
    Warning
    Ensure that your tooltips are maintained properly at all times, since they are also invoked for disabled items. Some browsers even invoke tooltips for keyboard actions, such as tabbing through the links.

    Resources

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

    Elements and Controls

    Implementation

    Formatted Text

    The formatted text control displays HTML text. You can format the text using HTML tags or embed formatted text.

    Example
    Example

    When to Use

    Use the formatted text control to:

    • Embed formatted HTML text.
    • Display longer texts, such as descriptions, legal texts, or manuals.
    • Display simple lists with bullet points or numbers.
    • Display code.

    Do not use the formatted text control to:

    • Display In-app help or explanations on how to use your app.
    • Display a simple and short text. Use the text control instead.
    • Display a semantically-colored text or a status. Use the object status instead
    • Display an object name with or brief additional information. Use the object identifier instead.
    • Display a number or sum. Use the object number instead.
    • Display a currency. Use the currency control instead.
    • Display a label. Use the label control instead.
    • Display a single headline. Use the title control instead.
    • Let the user to type in longer texts and format them. Use the rich text editor instead.

    Components

    By default, the control uses the standard font and headlines. It supports the following HTML tags:

    Text Styling

    HTML Tag Effect
    a Link or anchor
    abbr Abbreviation
    blockquote Quote
    cite Short quote
    code Code style
    em Italic text
    pre Preformatted text
    strong Bold text

    List

    HTML Tag Effect
    dl Description list
    dt Description term
    (of a description list)
    ul Unordered list
    ol Ordered list
    li List item
    (of an unordered or ordered list)

    Structure

    HTML Tag Effect
    br New line
    h1-h6 Headlines 1-6
    p Paragraph
    span Generic inline container

    Behavior and Interaction

    The formatted text control itself is not interactive. However, it can contain interactive elements, such as links and anchors.

    Responsiveness

    The text automatically adapts to the screen size unless you set a fixed width and/or height.

    Examples

    Here are some examples that use the various HTML tags.

    Formatted text - Numbered List
    Formatted text - Numbered List
    Formatted text - Bulleted list
    Formatted text - Bulleted list
    Formatted text with code
    Formatted text with code
    Formatted text - Quote
    Formatted text - Quote

    Top Tips

    • Use the different styling options carefully and not for decoration only.
    • Consider accessibility, such as color contrast.
    • SAP Fiori uses theming. Be aware that if you make custom changes to the HTML (such as changing colors), you need to take care of the theming part as well.

    Related Topics

    Elements and Controls

    Implementation

    HTML

    The HTML control allows you to display rich text or add freestyle HTML to your apps. This helps to cover use cases that would otherwise not be possible with standard SAP Fiori controls.

    Warning
    If you opt to use freestyle HTML, you must make sure that standard capabilities such as theming, accessibility, and responsiveness are supported.

    For more information, see Top Tips below.

    When to Use

    Information
    Be aware that implementing custom content costs time and effort for development.

    Use the HTML control to display:

    • (External) HTML content, such as work instructions or articles with images or videos.
    • User-created HTML content.
    • Content created with the rich text editor (as a live view during creation, or in read-only mode).
      (While formatted text only supports a limited set of tags, using HTML will give you the full set of HTML tags.)

    Do not use the HTML control to display:

    • In-app help or explanations on how to use your app. Use the Web Assistant instead.
    • A simple and short text. Use the text control instead.
    • A semantically-colored text or a status. Use the object status instead.
    • An object name with a brief descriptive text. Use the object identifier instead.
    • A number or total. Use the object number instead.
    • A currency. Use the currency control instead.
    • A label. Use the label control instead.
    • A single headline. Use the title control instead.

    Components

    Where possible, reuse existing controls inside your freestyle content. Do not reinvent standard controls, such as buttons or popovers. Instead, use the the available controls that are described in the SAP Fiori Design Guidelines.

    Behavior and Interaction

    When creating freestyle content, always apply the SAP Fiori design principles. Design your interactions on the basis of these principles and build upon existing, established patterns.

    If part of your content looks similar to an existing control, it should behave similarly. Do not change established interactions or patterns just because freestyle HTML allows you to, or because it looks more fancy. Users appreciate consistency.

    Responsiveness

    Using freestyle HTML comes with responsibilities. Making sure your content is responsive and adaptive is one of them.

    If you have a large amount of content, consider an adaptive approach: Don’t try to cram all the content you show on a desktop into a mobile version of your app. Instead, think about how your customers would use this app while away from their PC. For more information, see Multi-Device Support.

    Example

    The following image showcases how freestyle HTML can be used to create step-by-step work instructions by combining formatted rich text and videos. If you follow the SAP Fiori design guidelines, the freestyle section integrates seamlessly into the SAP Fiori application (shown here as a schematic object page layout).

    Freestyle HTML application example
    Freestyle HTML application example

    Top Tips

    Using freestyle HTML means that you are responsible for taking care of certain aspects that are otherwise covered automatically by standard SAP Fiori controls:

    • SAP Fiori design principles
    • Theming: Ensure correct theming if the HTML is part of the UI. This is not necessary if the HTML content is entirely user-created.
    • Accessibility: For example: contrast ratios, screen reader support, HCB
    • Multi-device support: Support all screen sizes for both touch- and mouse-enabled devices, including adaptive and responsive behavior.
    • Multi-browser support: Make sure your custom content is displayed correctly on all prevalent browsers.
    • Performance: Optimize performance and ensure that your custom content does not slow down the app or the user’s workflow.
    • Translatability: Make sure that your content is translated correctly.
    • Security: See the warning below.
    Warning
    By default, the HTML content (property: content) is not sanitized and is therefore open to XSS attacks. App teams must either sanitize the content themselves, or activate automatic sanitizing with the sanitizeContent property. For more information, see the API reference.

    Related Links

    Elements and Controls

    Implementation

    • HTML (SAPUI5 samples)
    • HTML (SAPUI5 API reference)

    P13n Dialog

    Intro

    The p13n dialog control allows users to personalize one or more of the following table attributes:

    • Columns: Visibility and order of columns
    • Sort: Sort criteria for table items
    • Filter: Filter criteria for table items
    • Group: Grouping table items by specific attributes

    These tabs can be shown in any combination, as required by the use case.

    The P13n dialog is intended for complex tables that have a large number of columns and require complex queries for sorting, grouping, and filtering.
    For simple tables, see the view settings dialog and table personalization dialog.

    The P13n dialog is opened using the corresponding buttons on the right-hand side of the table toolbar.

    Dialog buttons within the table toolbar
    Dialog buttons within the table toolbar

    Usage

    Use the P13n dialog if:

    • Users can personalize more than ~20 columns.
    • You need multiple personalization functions (columns, sorting, filtering, grouping, …)
    • You are using the analytical table.
    • Complex queries have to be built for the table.

    Do not use the P13n dialog if:

    • Users can personalize fewer than ~20 columns.
    • You only need a simple feature to show/hide columns.

    Responsiveness

    The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), it shows as a centered dialog. For size S (smartphones), it displays 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 Columns tab allows users to change the visible table columns and the order in which they are displayed.

    The available columns are shown as list items with checkboxes. The checkboxes for the columns that are currently being displayed are selected.

    The Show Selected / Show All button toggles the display between all columns and only those that are currently selected.

    Show/Hide

    To show or hide a column, users select or deselect the column checkbox.

    Reorder

    To change the order of the columns, users focus on a list item and use the buttons on the right-hand side of the table toolbar to move it up or down. The order of the columns from top to bottom corresponds to the order on the table from left to right.

    Search

    The search field in the table toolbar enables users to find a specific column more quickly. Matching columns are displayed as soon as the user starts to type.

    Column settings in the P13n dialog
    Column settings in the P13n dialog

    Sort

    On the Sort tab, the user can specify the sort criteria and sort order (ascending or descending).

    Each entry has two input fields: one for choosing the sort column, and one for choosing the sort order.

    Users can enter multiple sort criteria. Once a sort criterion is entered, a new line appears for entering another one.

    The order of the sort criteria reflects the order in which they are applied to the table.

    Sort settings in the P13n dialog
    Sort settings in the P13n dialog
    Information
    Using the sort feature for column headers replaces ALL sort options in the dialog!

    Filter

    The Filter tab allows users to filter the table information according to specific criteria.

    Users can add filters with the Add button or remove them by clicking the  (Remove Filter) icon at the end of each filter item.

    Column

    In the first input field, the user selects the column to be filtered. Any column can be selected, including columns that are not currently visible.

    Operator

    The second field contains the operator that is applied to the filter value (such as greater than or not before).

    To include or exclude filter criteria, the user selects the relevant operator from the Include or Exclude section of the dropdown list. For example, equal to to include a value, and not equal to to exclude it.

    If individual filter criteria have Boolean values, the operator is always “equal to” and the operator dropdown is disabled.

    P13n Filter Settings

    Available operators:

    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

    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 and the selected operator. For example, the value field for fixed or Boolean values could be a dropdown list, an input field with suggestions, or a date picker. You can also offer two or even more fields if the use case requires it.

    Information
    If there is a filter bar, use the filter bar functionality and deactivate the filter feature of the P13n dialog.

    Group

    The Group tab can be used to group the table data.

    In the selection field, the user can select a grouping criterion from a list of all available columns.

    For analytical tables, users can define more complex grouping scenarios. Once a grouping criterion is entered, a new line appears for entering another one. In addition, the Show Field As Column checkbox allows users to decide whether or not to display the corresponding column.

    The grouped table shows the individual values for the selected field as the group headers. Expanding the group shows all the corresponding table items.

    If you have defined multiple groups, the grouped table shows the individual values for the first selected field. Expanding the groups shows the subgroups and items in an expandable hierarchy.

    Warning
    To group by a specific column, that particular column must be marked as visible on the Columns tab!
    Group tab in the P13n dialog
    Group tab in the P13n dialog

    Guidelines

    On the table toolbar, offer separate buttons for each personalization 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

    Elements and Controls

    Implementation

    Busy Dialog

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

    Usage

    Use the busy dialog if:

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

    Do not use the busy dialog if:

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

    Responsiveness

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

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

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

    For more information, see the SAPUI5 Demo Kit.

    Components

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

    • Title: By default, it has no title. Define a title if you need to provide more context.
    • Text: Additional text can be added above the busy animation.
    • Cancel:(Property:showCancelButton) A Cancel button is displayed. There is no Cancel button by default. The label is also configurable via Property.cancelButtonText.
    • Icon: A custom animation icon can be set via Property:customIcon.

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

    Busy dialog with 'Cancel' button
    Busy dialog with 'Cancel' button
    Busy dialog without 'Cancel' button
    Busy dialog without 'Cancel' button
    Busy dialog - Lightweight version
    Busy dialog - Lightweight version

    Guidelines

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

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

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

    Developer Hint

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

    Busy Dialog with Text

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

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

    Busy Dialog with Text and Cancel Button

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

    Timing and Duration

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

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

    Resources

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

    Elements and Controls

    Implementation

    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 Views, Manage 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

    Image

    Images are a powerful way to capture the user’s attention and to communicate your message. You can use the image control to integrate images into your apps for dedicated purposes.

    When to Use

    Use the image control if:

    • You want to display decorative images. Decorative images serve as a visual eyecatcher and are useful to transport the brand identity. Usually, decorative images are used as hero images, headers, or background images.
    • You want to display images to support or enhance the page content (for example, visual representations of an object’s design, functions, or features).
    • You want to display images in a gallery.

    Do not use the image control if:

    • You want to display an image, initials, or a placeholder for a person. Use the avatar instead.
    • You want to display standardized images for business-related content (such as products, parts, product and company logos, or ad campaign images). Use the avatar instead.
    • You want to display icons. Use the avatar instead.
    • You want to display images with a transparent background. Use the avatar instead.
    • You want to display a placeholder image. Use the avatar instead.
    • You want to display pictures in a carousel. Use the carousel control instead.

    Behavior and Interaction

    Images can be non-interactive or interactive. Most commonly, clicking an image opens a lightbox or new tab/window and displays a larger version of the image. If you plan to open a popover or dialog, ensure that this information is announced by the screen reader beforehand (property: ariaHasPopup).

    The control also offers an image map option, where one image can have several click areas. Don’t use this option. It’s a relic of past times and has the potential to cause usability issues.

    Guidelines

    Screen Reader Details

    • Provide an alternative text for each image for screen reader users. Use the alternative text to describe the visual content specifically for blind or visually impaired users. Only decorative images don’t require an alternative text. The alternative text can also be helpful for sighted users if the image is not available or cannot be displayed.
    • An image can be decorative only. Images are considered as decorative if the same information is also conveyed in another content element and the image content is secondary. In other words, if the image doesn’t provide any additional value, it’s decorative. Decorative images are not announced by screen readers.
    • In addition to the alternative text, you can also provide screen reader users with more details about an image (property: ariaDetails). For example, images that display technical or scientific content may require background knowledge to understand the image. In the image details, you can include this background knowledge in in text form. For example, if an image shows the construction of a turbine, and certain formulas are required to understand it, the details would describe the formulas first and then relate them to the displayed image content.

    Image File and Quality

    • It is extremely important that you choose the right file format when saving your images. Four image formats are used consistently in browsers – PNG, JPG, GIF, and SVG.
    • When choosing the format for your image, always be conscious of the image quality and file size.
    • Optimize high-resolution images to avoid unnecessarily large files. Large image files can severely impede page performance.
    Good quality
    Good quality
    Poor quality
    Poor quality

    Responsiveness

    The image size adapts responsively to the screen size.

    You can also set a fixed width and/or height for an image.

    Images on size S
    Images on size S
    Images on size M
    Images on size M
    Images on size L
    Images on size L

    Examples

    Image on a small screen
    Image on a small screen
    Image in a carousel
    Image in a carousel

    Related Links

    Elements and Controls

    Implementation

    • Image (SAPUI5 samples)
    • Image (SAPUI5 API reference)

    Avatar

    The avatar is a control for displaying images. These can be user profiles, user initials, placeholder images, icons, or business-related images, such as product pictures.

    Usage

    Use the avatar to display:

    • An image, initials, or placeholder for a user
    • Standardized images for business-related content (such as products, parts, product and company logos, ad campaign images, …)
    • Icons
    • Images with a transparent background
    • Placeholder images

    Do not use the avatar if:

    • You want to include an image for any other use case (for example, to display decorative images or images in the content area that support or complement the content). Instead, use the image control.
    • You want to display pictures in a carousel. Instead, use the carousel control.
    • You want to show an interactive icon. Instead, use the button with an icon inside.
    Examples of a user image, user initials, and standard user placeholder icon
    Examples of a user image, user initials, and standard user placeholder icon
    Potential product image and product image placeholder
    Potential product image and product image placeholder
    Icon
    Icon

    Responsiveness

    The avatar control is adaptive and has five predefined sizes. These are the same for both compact and cozy form factors:

     

    Size rem Use for images in…
    XS 2 rem Table list items
    Card list items
    S 3 rem Card headers
    Card list items
    M 4 rem App headers for small screen sizes
    L 5 rem App headers for normal screen sizes
    XL 7 rem App headers for large screen sizes

    If your use case requires it, you can also set a custom size.

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

    Image Fit

    You can use the imageFitType property to specify how images fit to the avatar. There are two options: Cover (default) and Contain.

    Cover

    The size of the image is scaled up to completely cover the control area. As a result, parts of the image may be outside the shape.

    Use the Cover fit type if the focal point is in the center of the image.

    Contain

    The image is scaled down to fit into the control area. The entire image is displayed, but might not fully fill the shape. In this case, the control displays a default background color. The image itself is always centered inside the shape.

    Use the Contain fit type for product pictures that need to be displayed in full.

    Product image with the fit type 'cover' (left) and 'contain' (right)
    Product image with the fit type 'cover' (left) and 'contain' (right)

    Types

    Avatar – User Image, Initials, or Placeholder

    An avatar is a visual representation of a user in the digital space. Usually, an avatar displays the user in one of the following ways:

    • A user photo
    • The user’s initials
    • A placeholder icon instead of the user’s personal data (photo or initials)

    Always display avatars in a circle. This ensures that all users are represented equally on the user interface.

    Initials

    User image, user initials, and standard user placeholder icon
    User image, user initials, and standard user placeholder icon

    The initials stand for the first name(s) and last name(s) of a person – for example, JD for Jane Doe, or MvV for Marjolein van Veen. Which name comes first depends on the language-specific settings.

    Initials can have up to three alphabetical characters (A-Z, a-z). If more than 3 initials are required for longer names (such as Anna María Agustí Suárez), the gender-neutral placeholder icon is displayed instead. The placeholder is also used if the three letters don’t fit into the circle (for example, WWW).

    Some languages don’t build on an alphabet, or don’t use initials at all. In such cases, the gender-neutral person icon is displayed instead.

    User initials with 1, 2, and 3 characters
    User initials with 1, 2, and 3 characters

    Business Images

    Business images display a product, company, object, logo, or other business-related content.

    Always use a square for business images.

    Examples of product images
    Examples of product images

    Placeholder for Avatar and Business Images

    Placeholder images are used for both avatar and business images when no other image is available.

    • The default placeholder for an avatar is a gender-neutral person icon inside a circle.
    • The default placeholder for a business image is a neutral product icon inside a square.
    Default person and product placeholders
    Default person and product placeholders

    You can specify your own the default placeholder icon for business images.

    Always replace the default product icon if there is a more suitable icon for your use case and industry.

    Product placeholder images with custom icons
    Product placeholder images with custom icons

    Placeholder Background

    By default, the placeholder background color is set to blue (accent color 6). However, to add more visual variety to the UI, you can change the background color using one of the following options:

    • Accent colors – You can specify one of 10 different accent colors as the placeholder background color.
    • Random color – The control automatically picks a random color from the accent color palette.

    All accent colors can be themed.

    User initials in all ten accent colors
    User initials in all ten accent colors

    Placeholder for Decorative Images in the Content Area

    Use the background color ‘placeholder’ for decorative images in the content area, such as images in articles or longer descriptions. In these use cases, the primary focus is on the text and the image content is secondary.

    Decorative image in the content area
    Decorative image in the content area
    Placeholder image for secondary content
    Placeholder image for secondary content

    Images with Transparent Background

    You can display images with a transparent background. This can be useful for displaying descriptive illustrations and decorative pictures, for example.

    Image with transparent background
    Image with transparent background

    Icons

    You can use the avatar to display non-interactive display icons. Use the background color ‘placeholder’ to display the icon.

    Icons are usually part of an icon font. Do not use icons as images.

    If you want to put an action on the icon, use the button with an icon inside instead.

    Exemplary icons
    Exemplary icons

    Badge

    If an avatar is clickable, you can show an optional badge and icon.

    • Use a badge to indicate that the avatar is interactive.
    • Use an icon to indicate the action triggered by clicking the avatar.

    This feature gives users visual affordance of the available action, and is particularly useful for images. To ensure that the image and the badge icon are properly displayed, don’t use the badge for any avatar sizes smaller than S.

    When you use a badge and icon, always provide a corresponding tooltip for your avatar to indicate the action.

    Use the following standard icons and tooltip texts:

     

    Icon Tooltip Action
      Edit Image Edit the image. This can include multiple options, such as replacing an image, cropping, visual effects, or uploading a new image.
      Take a Picture Take a photo.
      Zoom In Zoom into the image.
    Avatars with badges
    Avatars with badges
    Avatars with badges and edit (left), camera (middle), and zoom in (right)
    Avatars with badges and edit (left), camera (middle), and zoom in (right)

    Guidelines

    • If you use a custom avatar size with initials or icons:
      • Make sure that the font size is consistent with the size of the control itself.
      • If your custom size is between two predefined sizes, use the font size for the smaller predefined size.
        Example: If your avatar is 5.5 rem (between sizes L and XL), use the font size for size L (2 rem).
    • Accessibility: Provide an alternative text for each avatar image for cases when the image is not available or can’t be displayed.
    • If the avatar is interactive, provide a tooltip to indicate the action (for example, Edit Image or Take a Picture).
    • Optimize high-resolution images to avoid unnecessarily large files. Large image files can severely impede page performance.
    Do
    Custom placeholder size with appropriate custom font size
    Custom placeholder size with appropriate custom font size
    Don't
    Custom placeholder size, but icon is too small
    Custom placeholder size, but icon is too small

    Styles

    You can add a very subtle border to the avatar (property: ShowBorder).

    Images with optional borders
    Images with optional borders

    Resources

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

    Elements and Controls

    Implementation

    Form / Simple Form

    Information
    This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

    For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

    Intro

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

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

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

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

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

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

    Types

    There are three types of forms:

    • Display-only: the data is presented only as label-value field pairs without editable fields.
    • Editable: the data is presented as label-input field pairs, so users can enter data.
    • Mixed: some fields are editable and some are not.
    Form in display-only mode
    Form in display-only mode
    Form in edit mode
    Form in edit mode
    Developer Hint
    The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
    Information
    Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

    Responsiveness

    The default settings of the control are not ideal for all possible use cases. Instead, applications can use one of the various layouts for the S, M, L and XL sizes.

    Column Layout

    The ColumnLayout control renders a form group in a column-based responsive way. Depending on its size, the group is divided into one or more columns.

    • XL – max. 6 columns
    • L – max. 3 columns
    • M – max. 2 columns
    • S – 1 column

    For size XL, we recommend using the full 6 columns for large forms with a lot of content. This gives you greater flexibility when organizing the content and the form groups.​

    To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns. The group elements are spread out into columns, depending on the number of group elements and their size.

    Example:

    • 4 columns and 2 groups: each group will use 2 columns.
    • 3 columns and 2 groups: the larger one will use 2 columns, the smaller one 1 column.

    The size of a group element will be determined by the number of visible elements assigned to it. If there are more groups than columns, every group uses only one column. So the last row of the form control will not be fully used. This will result in white space.

    The form elements are spread out to the columns of a group arranged in a newspaper-like order. The position of the labels and fields depends on the size of the used column. If there is enough space, the labels are next to the fields, otherwise above the fields.

    If you use the default form settings, each form group is displayed in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right side of the screen.

     

    The examples show how forms with one and two form groups are displayed with and without layout balancing.

    One form group with default arrangement
    One form group with default arrangement
    One form group with balanced column layout
    One form group with balanced column layout
    Two form groups with default arrangement
    Two form groups with default arrangement
    Two form groups with balanced column layout
    Two form groups with balanced column layout

    Responsive Grid Layout

    The responsive grid layout is a form using a responsive grid. Depending on the available space, the groups are rendered in one or multiple columns, and the labels are rendered in the same row as the fields or above the fields. This behavior can be influenced by the properties of this layout control.

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

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

    Breakpoints

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

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

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

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

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

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

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

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

    Label-Field Ratio

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

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

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

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

    Otherwise..

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

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

    Size S (Smartphones and Dialogs)

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

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

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

    Size M

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

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

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

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

    Form in size M (2:10:0)
    Form in size M (2:10:0)

    Size L

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

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

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

    Size XL

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

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

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

    Layout

    One Page, One Form

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

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

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

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

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

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

    One Page, Many Forms

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

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

    Various Layouts

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

    Size S (Smartphones and Dialogs)

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

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

    Size M (Tablet) – Full Screen

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

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

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

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

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

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

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

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

    Size L (Desktop Screens)

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

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

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

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

    Size XL (Desktop Wide Screens)

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

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

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

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

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

    Form with single group in a column layout - Size XL - (12:12:0)
    Form with single group in a column layout - Size XL - (12:12:0)

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

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

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

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

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

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

    Components

    The following UI elements can be placed in the form container:

    Guidelines

    • Order the form logically from a user’s perspective. For example, ask for a user’s name before asking them for their address.
    • Group related information by using form and group titles.
    • Use Column layout instead of Responsive Grid layout, if possible.
    • Try to arrange form groups (especially in size L and XL) in a way that the form:
      • Is easy to read and understand.
      • Does not contain too much white space (split groups if necessary).
    • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
    • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
    • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

    Label

    To avoid truncation, labels within forms wrap automatically.

    Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is to make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

    • A label is not a help text. Give each field a meaningful label. Make labels succinct, short and descriptive.
    • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property, and the asterisk will be inserted automatically.
    • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the style sheet. Do not write the colon manually in the label text.
    • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)

    Label Alignment

    • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
    • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
    Information
    The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

    Empty State Indicator

    If the form field doesn’t have a value, show an empty state indicator in display mode. This helps the user to better scan the form and perceive the field label and empty content as one unit.

    Developer Hint
    The empty indicator does not show by default. You need to activate it for the respective text (property: emptyIndicatorMode).
    Empty state indicator
    Empty state indicator

    Unit of Measurement

    You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

    If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

    Unit of measurement
    Unit of measurement

    Amount Alignment

    When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

    When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

    Data Loss Message

    Provide a data loss message if the user accidentally navigates away from the page (for example, if the user selects a list item in a list-detail layout and then clicks the the Back or Home button). For details about how the message is delivered and what text you can use, see Message Handling.

    Form Field Validation

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

    Field validation and validation report
    Field validation and validation report

    Input Assistance

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

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

    Error Prevention

    Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

    Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

    Placeholder

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

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

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

    Toolbar

    The form supports actions on form toolbar level as well as on group header level. Application development teams can add actions such as ‘Edit’, ‘Save’ or ‘Cancel’. If there is an action that only applies to the specific group on group level, it can only be added on the group header level of the specific group.

    Expanded/ Collapsed Form

    The form supports expand / collapse buttons on a per-group level. However, we recommend avoiding the usage of expand / collapse behavior on a form.

    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 Set

    The upload set control allows users to upload single or multiple files from a device (desktop, tablet, or phone) to an SAP Fiori app.

    Despite its name, the upload set is not limited to plain upload scenarios. Depending on the context or the access rights, some users may only be allowed to download the files uploaded by others. You can use the upload set control for both cases.

    When to Use

    Use the upload set control if:

    • You want to show a list of uploaded files that can be modified.
    • You want to allow users to add or remove several files, and to change the file names.
    • You are still using one of the older upload controls:
      • sap.ca.ui.FileUpload
      • sap.m.UploadCollection (deprecated since SAPUI5 version 1.88)

    Do not use the upload set control if:

    • The user can upload only one file to the app. In this case, use the sap.ui.unified.FileUploader control instead.

    Layout

    Default Layout and Actions

    Files are listed vertically. By default, each item has an Edit and a Remove button.

    While most file types have generic icons (for example documents, spreadsheets, or presentations), image files have a small thumbnail preview.

    You can control the visibility and the active state for all actions at item level.

    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.

    You can also define your own statuses. These usually refer to the object state in a workflow (such as Approved or Overdue). Statuses can be shown in different colors in accordance with the visual guideline for semantic colors.

    If multiple attributes or statuses are displayed, they are separated by a bullet.

    Layout – Attributes and statuses
    Layout – Attributes and statuses

    Technical Statuses

    Unlike the statuses mentioned above, technical statuses are not bound to a workflow or business process. They are mainly used to show the current editing status of an object (Draft, Locked, Unsaved Changes). For further uses and more details, see Object Display Components and Draft Handling.

    Layout – Technical statuses
    Layout – Technical statuses

    Behavior and Interaction

    Uploading Files

    The upload set offers two basic working modes:

    • Instant upload (default): Files are uploaded as soon as they are dropped onto the control or the OK button in the file selection dialog is clicked.
    • Manual upload: All added files are first collected in the front-end list, where the user needs to trigger the upload.
    Developer Hint
    Using the Boolean property instantUpload, you can determine whether files are uploaded immediately or whether the user needs to trigger the upload explicitly.

    If some users are only allowed to download the files uploaded by others, you can disable the upload option.

    Developer Hint
    The Boolean property uploadEnabled controls whether or not users are able to upload files.

    Unlike the deprecated Upload Collection control, the Upload Set control allows you to use a custom uploader.

    Developer Hint
    For an example of a custom uploader, see the SAPUI5 sample.

    Empty State

    If empty, the upload set provides a hint to use the Upload button or drag and drop to upload files. This hint already provides a large enough zone for users to drop their files.

    Interaction - No files found
    Interaction - No files found

    Drag and Drop

    Users can easily select one or multiple files from their computer and drag them onto the upload set to start the upload.

    As soon as a user starts to drag a file over the application, the hint changes into a drop zone, indicating where to place the file.

    Interaction - Drag and drop (1)
    Interaction - Drag and drop (1)

    As the user hovers over the drop zone, the color changes again to indicate that the file can be released.

    The upload process itself is the same as if a file had been added via the Upload button.

    Interaction - Drag and drop (2)
    Interaction - Drag and drop (2)

    Opening Files

    Files are opened by clicking the file name of the attachment. How the files open depends on the operating system and browser settings.

    On desktop devices, clicking the file name opens the program that has been assigned to this file type. In some cases, the files are opened directly in the browser if they are among the supported file types, like jpg, png or pdf. However, this also depends on the individual browser and its settings.

    Mobile devices usually open a dialog in which the user can select an app that supports this file type.

    Renaming Files

    The Edit function works identically on desktop and mobile devices.

    1. The user clicks the Edit (  ) button.
    2. The file name becomes an input field in which the existing name is highlighted. The icon buttons Edit (  ) and Remove (  ) are replaced by two text buttons: Rename and Cancel.
    3. When the user starts typing, the highlighted text is overwritten. Alternatively, the user can use the mouse or keyboard to change the selected text.
    4. The new file name can be validated in two ways:
      • The user clicks Rename.
      • The user presses Enter.
    • Interaction - renaming (1 of 4)
    • Interaction - renaming (2 of 4)
    • Interaction - renaming (3 of 4)
    • Interaction - renaming (4 of 4)
    Guidelines
    Specify the file name in the dialog.

    Removing Files

    The Remove function works identically on desktop and mobile devices.

    After clicking the Remove (  ) button for a file, the user is prompted to confirm the removal of the respective file.

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

    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.

    Examples:

    • Uploaded By: John Miller
    • Last Edited By: Donna Moore
    • Version 1.1
    Guidelines

    • Use a quick view to show this additional information.
    • Don’t use more than two or three linked attributes per item. Excessive use of clickable attributes overloads the UI with interactive elements and has a negative impact on usability.

    Responsiveness

    The upload set control offers full responsive behavior from small phones to large desktop screens. Uploading, downloading, renaming, and deleting works on all screen sizes. Texts that no longer fit into the available space are truncated.

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

    Example

    You can use the upload set control in different contexts, whenever users need to be able to upload multiple files. The example below shows the object page of a product, in this case a machine, with an Attachments tab containing several documents about its documents for assembly, service, and warranty.

    Upload set in object page
    Upload set in object page

    Other possible scenarios:

    • Warranty claim: Users need to upload images of a damaged item.
    • Product details: Editors can upload product pictures that will be shown in the online shop.
    • Service history: Whenever maintenance measures are performed, the service worker attaches a document to the object.

    Top Tips

    When to Show, Disable, and Hide Actions

    The Edit and Remove buttons are visible and enabled by default. If you don’t want to allow users to edit or remove uploaded files, hide the corresponding buttons.

    Don’t leave buttons enabled and then show an error message when the function isn’t available.

    Do
    Vertically align all actions
    Vertically align all actions
    Don't
    Don't position buttons differently. Place identical actions directly underneath one another.
    Don't position buttons differently. Place identical actions directly underneath one another.
    Do
    If users aren't allowed to use a certain function, hide the corresponding button.
    If users aren't allowed to use a certain function, hide the corresponding button.
    Don't
    Don't disable all actions. If users aren't allowed to use a certain action, don't show the corresponding button.
    Don't disable all actions. If users aren't allowed to use a certain action, don't show the corresponding button.
    Do
    If an action is unavailable, disable it (for example, if a file was uploaded by another user).
    If an action is unavailable, disable it (for example, if a file was uploaded by another user).

    Custom Uploader

    Developer Hint
    Unlike the deprecated Upload Collection control, the Upload Set control allows you to implement a custom uploader.

    Related Links

    Elements and Controls

    Implementation

    Upload Set

    The upload set control allows users to upload single or multiple files from a device (desktop, tablet, or phone) to an SAP Fiori app.

    Despite its name, the upload set is not limited to plain upload scenarios. Depending on the context or the access rights, some users may only be allowed to download the files uploaded by others. You can use the upload set control for both cases.

    When to Use

    Use the upload set control if:

    • You want to show a list of uploaded files that can be modified.
    • You want to allow users to add or remove several files, and to change the file names.
    • You are still using one of the older upload controls:
      • sap.ca.ui.FileUpload
      • sap.m.UploadCollection (deprecated since SAPUI5 version 1.88)

    Do not use the upload set control if:

    • The user can upload only one file to the app. In this case, use the sap.ui.unified.FileUploader control instead.

    Layout

    Default Layout and Actions

    Files are listed vertically. By default, each item has an Edit and a Remove button.

    While most file types have generic icons (for example documents, spreadsheets, or presentations), image files have a small thumbnail preview.

    You can control the visibility and the active state for all actions at item level.

    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.

    You can also define your own statuses. These usually refer to the object state in a workflow (such as Approved or Overdue). Statuses can be shown in different colors in accordance with the visual guideline for semantic colors.

    If multiple attributes or statuses are displayed, they are separated by a bullet.

    Layout – Attributes and statuses
    Layout – Attributes and statuses

    Technical Statuses

    Unlike the statuses mentioned above, technical statuses are not bound to a workflow or business process. They are mainly used to show the current editing status of an object (Draft, Locked, Unsaved Changes). For further uses and more details, see Object Display Components and Draft Handling.

    Layout – Technical statuses
    Layout – Technical statuses

    Behavior and Interaction

    Uploading Files

    The upload set offers two basic working modes:

    • Instant upload (default): Files are uploaded as soon as they are dropped onto the control or the OK button in the file selection dialog is clicked.
    • Manual upload: All added files are first collected in the front-end list, where the user needs to trigger the upload.
    Developer Hint
    Using the Boolean property instantUpload, you can determine whether files are uploaded immediately or whether the user needs to trigger the upload explicitly.

    If some users are only allowed to download the files uploaded by others, you can disable the upload option.

    Developer Hint
    The Boolean property uploadEnabled controls whether or not users are able to upload files.

    Unlike the deprecated Upload Collection control, the Upload Set control allows you to use a custom uploader.

    Developer Hint
    For an example of a custom uploader, see the SAPUI5 sample.

    Empty State

    If empty, the upload set provides a hint to use the Upload button or drag and drop to upload files. This hint already provides a large enough zone for users to drop their files.

    Interaction - No files found
    Interaction - No files found

    Drag and Drop

    Users can easily select one or multiple files from their computer and drag them onto the upload set to start the upload.

    As soon as a user starts to drag a file over the application, the hint changes into a drop zone, indicating where to place the file.

    Interaction - Drag and drop (1)
    Interaction - Drag and drop (1)

    As the user hovers over the drop zone, the color changes again to indicate that the file can be released.

    The upload process itself is the same as if a file had been added via the Upload button.

    Interaction - Drag and drop (2)
    Interaction - Drag and drop (2)

    Opening Files

    Files are opened by clicking the file name of the attachment. How the files open depends on the operating system and browser settings.

    On desktop devices, clicking the file name opens the program that has been assigned to this file type. In some cases, the files are opened directly in the browser if they are among the supported file types, like jpg, png or pdf. However, this also depends on the individual browser and its settings.

    Mobile devices usually open a dialog in which the user can select an app that supports this file type.

    Renaming Files

    The Edit function works identically on desktop and mobile devices.

    1. The user clicks the Edit (  ) button.
    2. The file name becomes an input field in which the existing name is highlighted. The icon buttons Edit (  ) and Remove (  ) are replaced by two text buttons: Rename and Cancel.
    3. When the user starts typing, the highlighted text is overwritten. Alternatively, the user can use the mouse or keyboard to change the selected text.
    4. The new file name can be validated in two ways:
      • The user clicks Rename.
      • The user presses Enter.
    • Interaction - renaming (1 of 4)
    • Interaction - renaming (2 of 4)
    • Interaction - renaming (3 of 4)
    • Interaction - renaming (4 of 4)
    Guidelines
    Specify the file name in the dialog.

    Removing Files

    The Remove function works identically on desktop and mobile devices.

    After clicking the Remove (  ) button for a file, the user is prompted to confirm the removal of the respective file.

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

    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.

    Examples:

    • Uploaded By: John Miller
    • Last Edited By: Donna Moore
    • Version 1.1
    Guidelines

    • Use a quick view to show this additional information.
    • Don’t use more than two or three linked attributes per item. Excessive use of clickable attributes overloads the UI with interactive elements and has a negative impact on usability.

    Responsiveness

    The upload set control offers full responsive behavior from small phones to large desktop screens. Uploading, downloading, renaming, and deleting works on all screen sizes. Texts that no longer fit into the available space are truncated.

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

    Example

    You can use the upload set control in different contexts, whenever users need to be able to upload multiple files. The example below shows the object page of a product, in this case a machine, with an Attachments tab containing several documents about its documents for assembly, service, and warranty.

    Upload set in object page
    Upload set in object page

    Other possible scenarios:

    • Warranty claim: Users need to upload images of a damaged item.
    • Product details: Editors can upload product pictures that will be shown in the online shop.
    • Service history: Whenever maintenance measures are performed, the service worker attaches a document to the object.

    Top Tips

    When to Show, Disable, and Hide Actions

    The Edit and Remove buttons are visible and enabled by default. If you don’t want to allow users to edit or remove uploaded files, hide the corresponding buttons.

    Don’t leave buttons enabled and then show an error message when the function isn’t available.

    Do
    Vertically align all actions
    Vertically align all actions
    Don't
    Don't position buttons differently. Place identical actions directly underneath one another.
    Don't position buttons differently. Place identical actions directly underneath one another.
    Do
    If users aren't allowed to use a certain function, hide the corresponding button.
    If users aren't allowed to use a certain function, hide the corresponding button.
    Don't
    Don't disable all actions. If users aren't allowed to use a certain action, don't show the corresponding button.
    Don't disable all actions. If users aren't allowed to use a certain action, don't show the corresponding button.
    Do
    If an action is unavailable, disable it (for example, if a file was uploaded by another user).
    If an action is unavailable, disable it (for example, if a file was uploaded by another user).

    Custom Uploader

    Developer Hint
    Unlike the deprecated Upload Collection control, the Upload Set control allows you to implement a custom uploader.

    Related Links

    Elements and Controls

    Implementation

    Calculation Builder

    The calculation builder can be used to create complex expressions that combine numeric constants and variables with arithmetic and logical operators. The expressions can be entered using a visual editor or a text editor with three available layout options.

    Usage

    Use the calculation builder if:

    • You need to create or edit complex arithmetic expressions.
    • You need to define or modify business KPIs.
    • You need to keep the dependencies of the underlying calculations and to be able to expand them.

    Responsiveness

    The calculation builder is fully responsive, and uses 100% of the width provided by the container in which it is embedded. For size S, it is mandatory to use 100% of the page width.

    Depending on the available width, the calculation content is broken into separate lines in order to keep the native vertical scrolling for the whole page.

    Calculation builder - Size L
    Calculation builder - Size L
    Calculation Builder - Size M
    Calculation Builder - Size M
    Calculation builder - Size S
    Calculation builder - Size S

    Layout

    The calculation builder provides three different types of layout:

    • By default, the header toolbar and both the visual and textual editors are displayed. The header toolbar includes a toggle button for hiding or displaying the textual editor.
    • Only the header toolbar and the textual editor are displayed, making the calculation builder a text-only control.
    • The header toolbar and visual editor are displayed. The header toolbar includes buttons for arithmetic and logical operators, as well as variables. The toolbar buttons show the user which operations and variables are supported.
    Header toolbar + visual editor + textual editor (default)
    Header toolbar + visual editor + textual editor (default)
    Header toolbar + textual editor only
    Header toolbar + textual editor only
    Header toolbar (with operators and variables) + visual editor
    Header toolbar (with operators and variables) + visual editor

    Layout Examples

    The following examples show how the different layout types appear on the UI.

    Default layout
    Default layout
    Header toolbar with expression operators and textual editor
    Header toolbar with expression operators and textual editor
    Header toolbar with textual editor only
    Header toolbar with textual editor only

    Components

    The calculation builder can include thee components:

    • A header toolbar
    • A visual editor
    • A textual editor

    Header Toolbar

    A – Title: Provides a short and meaningful summary of the expression.

    B – Textual Editor Toggle: Enables the user to hide the Expression Output section and work with the visual editor only

    C – Expand All Variables: Allows the user to expand all the variables included in the expression and see all the underlying calculations used to compose the variable.

    D – Full Screen: Toggles the full screen view.

    E – Divider Line: The divider separates the header toolbar from the content below.

    Header toolbar
    Header toolbar

    Visual Editor

    A – Functions: Functions require brackets. The initial bracket is automatically inserted after the function name. Only a limited subset of functions is supported by default. However, you can define any custom function you need using the API.

    B – Variables: A custom set of available KPIs, such as revenue, assets, or expenses. KPIs are predefined by each application.

    C – Constants: Enables user to type the values directly as standalone constants or as part of a function.

    D – Operators: Arithmetic, logical, and comparison operators are available.

    E – New Element: The default button of each expression triggers a dialog to add a new function, variable, operator, or constant.

    Visual editor
    Visual editor

    Textual Editor

    The textual editor contains a plain text representation of the expression entered in the visual editor.

    If the user copies an arithmetic expression from an external application and pastes it to the textual editor, the expression displayed in the visual editor will be updated automatically. The same applies the other way round: if the user enters an expression using the visual editor, the textual editor gets updated, which can be used to copy the expression to an external application.

    Textual editor
    Textual editor

    Behavior and Interaction

    Inserting New Calculation Elements

    The user has two options for adding an operator, constant, variable, function, or reference to an expression:

    • By clicking the New Element button
    • By typing it directly into the textual editor field, which makes it appear in the visual editor as well.

    The New Element button triggers a dialog with the selection of all available calculation elements.

    Developer Hint
    You can customize the calculation elements available to your users, add custom functions, load a specific list of variables, or disable any of the default calculation elements.
    Selecting a reference
    Selecting a reference
    'New Element' dialog
    'New Element' dialog
    Selecting a variable
    Selecting a variable
    Selecting a function
    Selecting a function
    Selecting an operator
    Selecting an operator

    Expanding Variables

    There are two ways a user can expand a variable to see the underlying structure of the variable.

    • Expand an individual variable by clicking the Expand Variable button.
    • Expand all variables by clicking the Expand All Variables button in the header toolbar.

    In both cases, a confirmation message is displayed warning the user that this action is irreversible and variables cannot be collapsed back.

    When a variable is expanded, the user can also remove the dependency on the original variable, if needed.

    Warning
    Expanding a variable is currently an irreversible action, and the dependency on the original variable can only be restored if you insert the original variable again as a new calculation element.
    Selecting a variable to expand
    Selecting a variable to expand
    Confirming the variable expansion
    Confirming the variable expansion

    Guidelines

    When the default layout is used, displaying both the visual and textual editors, we advise against adding the editor buttons for operators, constants, functions, and variables to the header toolbar.

    Resources

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

    Elements and Controls

    Implementation

    Select Dialog

    The select dialog enables users to select one or more items from a comprehensive list. The select dialog comes with a list of entries and a search field to filter the list.

    A more enhanced dialog for single selection and multiselection is the value help dialog as it offers range selection and excluding functions.

    Usage

    Use the select dialog if:

    • Users need to select one or more entries from a comprehensive list that contains multiple attributes or values.

    Do not use the select dialog if:

    • Users need to pick one item from a predefined set of options that contains one attribute or value only such as languages. In this case, consider using the combo box or select instead.
    • Your use case requires more enhanced functionalities such as a selection based on ranges. For the selection of values, consider using the value help dialog instead.
    • Your use case requires tabs, filters, or an Add New functionality in the select dialog. In this case, use a standard dialog instead.
    Information
    For more information on which selection control to choose, see the selection control overview.

    Responsiveness

    The display of the select control depends on the device. On phones, the selection list takes up the whole screen. On desktop and tablet devices it appears as a popover.

    Size S

    Single select dialog in full screen on smartphone
    Single select dialog in full screen on smartphone
    Multi-select dialog in full screen on smartphone
    Multi-select dialog in full screen on smartphone

    Size M

    Single select dialog on tablet
    Single select dialog on tablet
    Multi-select dialog on tablet
    Multi-select dialog on tablet

    Size L

    Single select dialog on desktop
    Single select dialog on desktop
    Multi-select dialog on desktop
    Multi-select dialog on desktop

    Components

    Dialog Header

    You need to set the title of the dialog header (1). We recommend the following form:

    Single selection

    Select

    Example: Select Product

    Multi-selection

    Select

    Example: Select Products

    Search

    The first element in the dialog is a standard search field (2).

    Info Toolbar

    The info toolbar (3) is only available in multi-selection mode. It shows the number of selected items in the following form:

    Selected :

    Example: Selected Products: 2

    Content

    The content area (4) can be filled with any list content inherited from the list item base, such as standard list items, display list items, and feed list items. You can set the content to be displayed as grouped.

    Button Toolbar

    The button toolbar (5) contains two buttons: Select and Cancel. Select takes over the selection, while Cancel resets the selection to the state it was in when the dialog was opened.

    Components of the select dialog. Left: single select, right: multi-select
    Components of the select dialog. Left: single select, right: multi-select

    Behavior and Interaction

    The select dialog can be called from any control. The most common trigger is an input field with a selection icon, also known as a “value help field”, or F4. Alternative triggers are buttons or icons, which add items to an existing list.

    Single Select

    Once users select an entry, the select dialog is closed and the selected entry is taken over. If applicable, the entry is displayed in the field from which the dialog was triggered.

    Multi-Select

    In the multi-select version of the select dialog, checkboxes are provided for choosing multiple entries. The selection is taken over when the user closes the dialog via OK. Cancel closes the dialog without taking over the selected values. An infobar indicates the number of selected items.

    Search

    The user can search items.

    Resize and Drag Dialog

    You can make the select dialog resizable and draggable by setting the corresponding properties (also called resizable and draggable) to “true”.

    A resizable dialog makes sense if the items inside have long names or descriptions.

    A draggable dialog allows users to see the app content behind the dialog.

    Guidelines
    Both features are optional. However, even if you only need one, always set both of them to “true” to ensure consistency.

    Guidelines

    List Options

    If you need to indicate that none of the selection options are selected, or you need to allow the user not to select an option, provide (None) as an option and place it at the beginning of the list.

    If you need to indicate that all items apply (for example, as a list filter), provide All as an option and place it at the beginning of the list.

    Select list with '(None)'
    Select list with '(None)'

    Search Behavior

    Two types of search behavior are available:

    (1) A live search, also known as “search-as-you-type” (property: liveChange), which is triggered by each character that the user enters or deletes.

    (2) A manual search, which is triggered explicitly after the user enters text in the search field and clicks the Search icon or presses the ENTER key.

    Although app developers need to decide themselves which search to use, we recommend implementing the live search whenever possible. Use the manual search only if the amount of data is too large and your app would otherwise run into performance issues. For more information, check out the article on search.

    Reset/Remember Selections

    By default, the selection is reset when the dialog is closed. This allows users to make a new selection when they reopen the dialog and makes sense when users need to add multiple items to a table.

    Selection is reset after the dialog is closed
    Selection is reset after the dialog is closed

    However, if your use case requires selections in a dialog to be remembered so that the user can make corrections, you can set the rememberSelections function in the select dialog to “true”. When users exit the dialog by clicking Cancel, the selection is then restored to the state it was in when the dialog was opened.

    Selection is remembered after the dialog is reopened
    Selection is remembered after the dialog is reopened

    This also works in single-select dialogs. There, if users click the remembered item again, the dialog closes and they do not have to explicitly click Cancel.

    Infobar

    In multi-selection mode, an infobar shows the number of selected items. Use the following format:

    Selected: [Number of selected items]
    Example: Selected: 2

    Note that the infobar is not “sticky”. When the user scrolls down the list, the infobar scrolls off the screen.

    Infobar States

    The infobar has two states – active and non-active (non-clickable). For more information see Infobar States.

    Infobar - Active state
    Infobar - Active state
    Infobar - Non-active state
    Infobar - Non-active state

    “Clear” Button

    The Clear button allows users to clear all the selected items. By default, the button is not shown. To display the button, set the showClearButton property to “true”.

    Select dialog with 'Clear' button
    Select dialog with 'Clear' button

    Content

    By default, the select dialog comes with a growing feature (property: growing = “true”). We recommend disabling the growing feature and setting this property to “false”. This ensures that all items in the table are loaded at once, and that the “Items selected” count, the search, and select/deselect features all work properly.

    Resources

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

    Elements and Controls

    Implementation

    Icon Tab Bar

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

    There are two key use cases:

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

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

    Usage

    Use the icon tab bar if:

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

    Do not use the icon tab bar if:

    • You plan to use only one single tab.

    Responsiveness

    The icon tab bar stretches horizontally, which often exceeds the available width on small screens. It responds to limited space by offering a scrolling mechanism.

    Responsiveness – Text tabs
    Responsiveness – Text tabs
    Responsiveness – Icon tabs
    Responsiveness – Icon tabs

    In addition to the responsive overflow behavior, the icon tab bar can be forced into compact mode or even react dynamically to the application’s global density setting. See the Tab Density section for details.

    If there is not enough space to show all the tabs on the main tab bar, an overflow menu appears, containing all the remaining tabs that do not fit on the screen. By default, the overflow menu appears on the far right (see image “Responsiveness – Overflow on the far right”).

    Another option is to display an overflow menu on both sides of the icon tab bar. The use of this overflow behavior depends on whether the order of the tabs is fixed or can be rearranged:

    Responsiveness – Overflow on the far right
    Responsiveness – Overflow on the far right

    Layout

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

    Types

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

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

    Text Only

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

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

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

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

    Counters and Text Tabs

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

    Do not use the old layout that shows the counters on top of the labels (Headermode = “Standard”).

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

    Icon Tabs

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

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

    Types – Icons with counters
    Types – Icons with counters

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

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

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

    Tabs as Filters

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

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

    Tabs as Process Steps

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

    To connect the process steps, you can use the triple-chevron icon ( ) from the SAP icon font (technical name: process). Do not use the triple-chevron icon in the anchor bar of an object page.

    If the process steps have a fixed order, set the property TabsOverflowMode to “StartAndEnd” to show an overflow menu on both sides and to keep the order of the tabs intact.

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

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

    Hierarchies

    The tab bar supports hierarchies, allowing multiple tabs underneath one main tab. This way, you can group several tabs together, with the main tab acting as a headline.

    Subtabs

    The example on the right shows the main tab Notes with two subtabs, Internal and External, with no specific hierarchy except for their order.

    Types – Subtabs
    Types – Subtabs

    Nested Tabs

    Nesting allows deeper hierarchies with indentations to indicate the level of each tab.

    By default, the property maxNestingLevel is “0” (zero). To enable nesting, adjust this value to the highest level of nesting that your app allows.

    Types – Nested tabs
    Types – Nested tabs

    Behavior and Interaction

    Clicking a Tab

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

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

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

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

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

    Changing the Order of Tabs

    You can allow users to rearrange the tab order in a desktop environment (property: enableTabReordering). If this feature is enabled, users can drag and drop tabs to reorder them, either directly on the tab bar or inside the overflow menu.

    It is also possible to drag and drop tabs from the tab bar to the overflow menu and vice versa.

    If nesting is enabled (property maxNestingLevel > 0), users can choose the level at which they want to drop a tab.

    Dragging a tab activates a visual indicator for positioning the tab. For example, dragging tab 8 on top of tab 5 makes tab 8 the child of the now highlighted tab 5 (see image 1).

    If the user drags a tab between two other tabs, the indicator shows the level at which level the tab will be nested (see image 2).

    Interaction - Tab nesting using drag and drop (1 of 2)
    Interaction - Tab nesting using drag and drop (1 of 2)
    Interaction - Tab nesting using drag and drop (2 of 2)
    Interaction - Tab nesting using drag and drop (2 of 2)
    Guidelines
    Do not use this feature for:

    • Tabs as process steps:
      This ensures that consecutive steps do not get mixed up.
    • Anchor bar navigation:
      Sections that are represented in the anchor bar have a fixed order.

    Styles

    Tab Density

    The default responsive design of the icon tab bar applies to both compact and cozy modes. However, in addition to this responsive behavior, the control can be forced into a compact mode, or even react dynamically to the application’s global density setting. This feature can be used to:

    • Save vertical space on the page (applies to both text and icon tabs)
    • Save horizontal space (icon tabs only; this is especially helpful when there are many tabs)
    • Generally use less space on mobile devices
    • Reduce noise when there are already more important visual elements on the screen (primarily icon tabs)

    The property for the override is called tabDensityMode, which can be set to “Cozy”, “Compact”, or “Inherit”. “Cozy” is the default setting that renders the control in its regular dimensions. “Compact” reduces the control’s height and icon sizes (if applicable), even if there would be enough space for the cozy design. “Inherit” instructs the control to follow the global density mode defined for the application. For backward compatibility, the default setting is “Cozy”.

    The following image shows some types of tabs with their default style (cozy, left) and the reduced density mode (compact, right).

    Style – Tab density
    Style – Tab density

    Colors

    The two different styles (round tabs and text only) are discussed in the Types section. In both cases, you can use semantic colors to give users additional orientation.

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

    Developer Hint
    To apply semantic colors to the icons and the text-only tabs, you can use the property sap.ui.core.IconColor.

    Example

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

    Styles – Colors
    Styles – Colors

    Badge

    A tab can have an attention badge to indicate that new items were added to that tab. Only display a badge if new items are triggered from outside the app. Do not display a badge when users add new items themselves.

    Icon tab with an attention badge
    Icon tab with an attention badge

    Badge in Default or Semantic State

    You can add a badge to all types of icon tab bar.

    The badge inherits the state of its tab (default state or semantic state):

    • For the default tab state, the default red badge is displayed.
    • If the tab has a semantic state, the badge inherits the semantic color for the current state.

    Don’t mix tabs in the default state with tabs that have a semantic state.

    Badge for the default state / semantic state

    Badge Interaction

    The badge becomes part of the active area of the tab. When the user activates a tab with a badge, the badge disappears. If a new item is added to the tab that is currently open, no badge is shown.

    In addition, the badge inherits the interaction of its tab. For example, if a tab is moved using drag and drop, the attention badge moves with it.

    Interaction example: Activating a tab with a badge
    Interaction example: Activating a tab with a badge

    Overflow Menu

    If there isn’t enough space to show all the tabs on the main bar, an overflow menu appears on the right by default, containing all the remaining tabs. Depending on the use case, an overflow menu can also appear on both sides (for example, for process steps or anchor bar navigation).

    A badge on the chevron icon   indicates that a tab within the overflow menu has received new items. The tab in question is indicated by a second badge on the item in the overflow menu.

    Badge within overflow menu
    Badge within overflow menu

    Guidelines

    Apply the styles as follows:

    • Icons only: Use this option if you have only 4-5 tabs that can be very clearly identified by their icon. If a short description is needed, use icons and labels.
    • Text only: Use this option if you have more than 4-5 tabs, or if there are no clear icons to represent the content. The text-only style also allows for longer labels. Set the property HeaderMode to “Inline”.
    Do
    Counters – Inline layout ('HeaderMode' set to 'Inline')
    Counters – Inline layout ('HeaderMode' set to 'Inline')
    Don't
    Counters – Old layout ('HeaderMode' set to 'Standard')
    Counters – Old layout ('HeaderMode' set to 'Standard')

    If you use icon tabs, ensure the following:

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

    Implement the focus as follows:

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

    Additional guidelines:

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

    Resources

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

    Elements and Controls

    Implementation

    View Settings Dialog

    The view settings dialog helps users to sort, filter, or group data within a list or a table. The dialog is triggered by icon buttons in the table toolbar.

    Usage

    We recommend making each feature (sort, filter, group) available as a separate button in the table toolbar (see Button Placement below). Each button then triggers a separate dialog. If specifically required, you can combine the dialogs into one with a segmented button acting as tabs to switch between the sort, filter and group options. Note: In a combined dialog, the Reset button resets all tabs.

    Use the view settings dialog if:

    • Users need to sort line items in a manageable list or table (up to about 20 columns).
    • You need to offer custom filter settings in a manageable list or table (up to about 20 columns).
    • Users need to group line items in a manageable list or table (up to about 20 columns).

    Do not use the view settings dialog if:

    • You have complex tables (more than about 20 columns).
    • Users need to rearrange columns within the table. Use the table personalization dialog instead.
    • Users need very specific sort, filter, or column sorting options within complex tables. Use the P13n dialog instead.

    Button Placement

    Use distinct icon buttons for the sort, filter, and group settings. Place the icons in the following order:   (Sort),  (Filter),   (Group).

    Do not place Sort, Filter, or Group buttons in the footer toolbar if they refer to a table.

    For more information about the button placement, see Sort, Filter, Group (Generic) in the table toolbar article.

    Sort, Group, and Filter a List

    You can also offer the view setting features for a list.

    Responsiveness

    The popover dialog appears as a modal window on desktop and tablet screen sizes, but uses the full screen on smartphones.

    The view settings dialog is a composite control that consists of a modal dialog with a maximum of three tabs with lists of attributes. Each helps the user to either sort, filter, or group a table or list. If the use case requires only a sort feature, for example, you can hide the filter and group tabs.

    The dialog is triggered by one of the icon buttons in the table header
    The dialog is triggered by one of the icon buttons in the table header
    View settings dialog - Size S
    View settings dialog - Size S
    View settings dialog - Size M
    View settings dialog - Size M
    View settings dialog - Size L
    View settings dialog - Size L

    Behavior and Interaction

    The sort, filter, and group features can all be applied to a table simultaneously.

    Sort

    The sort dialog shows two groups of sort settings. The first group offers general Ascending and Descending sort options. The second group offers attributes that fit the use case, such as Product, Supplier, Weight, or Price. The attributes can match the table columns, but because a table column can also contain several data points, such as “Name” and “Surname”, the attributes allow an attribute to be shown for each data point.

    Users can select attributes using the radio buttons. Clicking OK closes the dialog and shows the table items in the selected order.

    If a combined dialog is used, the first tab is the sort feature.

    View settings dialog - Sort
    View settings dialog - Sort

    Filter

    The filter dialog can offer a single filter selection list, a multi-filter selection list, or a category list. The category list provides an overview, and allows the user to drill down to detailed filter selection lists.

    In a combined view settings dialog, filtering is on the second tab.

    Filter Selection List – Single Selection

    The dialog offers one selection list with radio buttons to select a filter. This list is useful for offering a list of preconfigured filters for a specific use, such as “Products with numbers ‘starting between 100 and 200’ with status ‘in stock’ and color ‘green’”.

    Filter Selection List – Multi-Selection

    You can also offer a multi-selection list. For example, a user might want to show all open items for both “Company A” and “Company D”.

    Show Selected Only

    If the user clicks the    button (Show Selected Only), only the selected filters are shown (for example, “Company A” and “Company D”). Clicking the button again shows all of the available filter values.

    Multiple filters selected
    Multiple filters selected
    Multiple filters with 'Show Selected Only' option active - only selected filters are shown
    Multiple filters with 'Show Selected Only' option active - only selected filters are shown

    Category List

    The filter dialog shows a single list of general filter categories depending on the use case, like Price or Height. The user chooses a category by clicking the list item, such as Price. As this is a simple drilldown, these categories do not have radio buttons. The follow-on dialog shows a list of optional filter settings in the Price category. These filters, such as Less than 100, depend on the use case. The user chooses a specific filter setting by selecting one of the radio buttons offered in this list. Clicking OK closes the dialog and shows the table items filtered by the selected attribute. The infobar shows which filter has been set.

    Example: Filter Dialog with Category List

    1) Select a category
    1) Select a category
    2) Option to refine filters for the selected category (here: 'Weight')
    2) Option to refine filters for the selected category (here: 'Weight')
    3) Infobar showing the filter setting for a table view filtered by 'Weight'
    3) Infobar showing the filter setting for a table view filtered by 'Weight'

    Free-Form Apps

    You can also customize your own filter UIs, for example, to support date picking.

    Filter Values

    Filters can correspond to single values as well as groups, such as “<100.00 EUR”.

    Filter Reset

    The Reset button on the filter tab resets all filter settings.

    Removing Filters

    In single selection lists, offer a Not Filtered option. This enables users to remove existing filters.

    Group

    The group dialog shows two groups of attributes. The first group offers a general Ascending or Descending order, which allows the user to select the order in which the defined groups appear. The second group offers attributes that fit the use case, such as Type or Supplier.

    You can also offer an attribute like Price to group data in a table.

    Users can choose attributes using radio buttons or checkboxes. Clicking OK closes the dialog and shows the table with items grouped below headers.

    In a combined view settings dialog, the group feature is the third tab.

    Dialog for choosing an attribute from the group tab
    Dialog for choosing an attribute from the group tab
    Table view grouped by supplier – Group headers divide the list
    Table view grouped by supplier – Group headers divide the list

    Naming Group Headers

    Be sure to name the group headers as follows: <Category Name>: <Value/Range>

    Examples:

    • Category: Accessories
    • Supplier: Red Point Stores.

    Guidelines

    On the table toolbar, use different buttons for each function (sort, filter, group). With each button, open the View Settings dialog with just the corresponding tab.

    If possible, give users the option not to filter or group. For sorting, this is only necessary if the use case calls for an unsorted list. In all three cases, show this option as the first entry in the list of criteria (remember to include the brackets):

    • (Not Sorted)
    • (Not Filtered)
    • (Not Grouped)

    Resources

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

    Elements and Controls

    Implementation

    Standard List Item

    The standard list item is a type of list item used in simple lists. You can use it to display a simple data point (title) or a set of data, such as a product title and a few product attributes.

    Standard list item with title only
    Standard list item with title only
    Standard list item with image, title, and short description
    Standard list item with image, title, and short description

    Usage

    Use the standard list item if:

    • You want to display a simple set of data in a list.
    • You want to display a simple set of data as part of a list within the select dialog.

    Do not use the standard list item if:

    Components

    The standard list item can consist of the following parts:

    • Title (mandatory). By default, the title font is larger if there’s no description. If you have list items with and without a description, this results in differently sized titles that are harder to read. In this case, switch off the title size adaptation (property: AdaptTitleSize).
    • Visual: icon or image (optional): Either displayed in the form of an icon from the SAP icon font or as an image.
    • Short description (optional).
    • Status (optional): This semantic information is equivalent to the object status. It’s usually displayed as colored text and displays the status. Keep the status text as short as possible.
      As an alternative, you can invert the display to place a stronger focus on the status
      (property: infoState). Use the inverted display only if the status is critical for your use case and requires immediate action.
    Standard list item with all options (image, title, short description, status)
    Standard list item with all options (image, title, short description, status)

    Responsiveness

    The title and short description can wrap and truncate. However, we recommend keeping the text as short as possible. The semantic information text is always displayed in full.

    Standard list item with a truncated title
    Standard list item with a truncated title
    Standard list item with wrapped and truncated title and description
    Standard list item with wrapped and truncated title and description

    Behavior and Interaction

    The list item behavior is identical for all list item types. For more information, see the interaction details in the list overview article.

    Examples

    Here are a few examples of standard list items:

    Standard list items in a list
    Standard list items in a list
    Standard list item with a title and status
    Standard list item with a title and status
    Standard list item with a title and short description
    Standard list item with a title and short description
    Standard list item with a counter in list selection
    Standard list item with a counter in list selection
    Standard list item with an icon, title, and short description
    Standard list item with an icon, title, and short description
    Standard list item with an icon, title, short description, and checkbox for selection
    Standard list item with an icon, title, short description, and checkbox for selection
    Borderless standard list item
    Borderless standard list item

    Resources

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

    Elements and Controls

    Implementation

    Chart Popover

    A chart popover is used to display information or an action related to the selected data points of a chart.

    By default, the chart popover:

    • Displays dimension members and measure values fed into the chart that relate to the data point.
    • Displays the number of selected items when in multiselection mode.
    • Does not display related actions.

    The entire content of the popover can be changed or a related action can be added at the end.

    Selection and Popover

    The content displayed in the popover depends on the selection mode; in other words, whether the chart is in single-selection or multiselection mode.

    When the user clicks an item that is not selected, the popover appears displaying information about this selected item only. The item that was previously selected becomes deselected.

    In Single-Selection Mode

    When the user clicks an item that is not selected, the popover appears with information about this selected item only. The item that was previously selected becomes deselected.

    Popover in single-selection mode
    Popover in single-selection mode

    In Multiselection Mode

    When the user clicks an item that is not selected, the item is added to the selection. The popover appears with information about the last selected item and any other selected items. When the user clicks an item that is already selected, this item is removed from the selection. If there are no more selected items, the popover disappears.

    Popover in multiselection mode
    Popover in multiselection mode

    Structure

    The following image provides an overview of the popover structure:
    1. Related information about last selected item
    2. Number of selected items
    3. Related actions

    For more information, see the table below.

    Popover structure
    Popover structure
    Section Explanation Provided by default Customizable
    Related information about last selected item Contains all related information about the last selected item. In single-selection mode, this is the single selected item. In multiselection mode, this is the last item added to the selection. Yes Yes. If the app developer wants different information, this section should be replaced entirely. Text only cannot be changed and another value cannot be added.
    Number of selected items Displays the number of items in the selection. Only used when multiple items are selected. Yes No
    Related actions Displays actions that act on all selected items. No Yes. The app developer can add its own actions. See the section below about related actions.

    Default Information

    By default, the chart popover displays all information related to the last selected item. The first row displays dimension members. A color marker is displayed and uses the same color as the selected item in the chart. Measures are displayed below with their associated values.
    Default display
    Default display

    With multiple dimensions, the dimension members are concatenated and displayed in the following order:

    • Firstly, the dimensions displayed in the legend.
    • Secondly, the dimension displayed in the axis. If there is more than one dimension in the axis, the dimension closest to the axis is displayed first.

    The first row is wrapped if necessary.

    Multiple dimensions display
    Multiple dimensions display
    If the selected item contains multiple measures, all measures are displayed above the category.
    Multiple measures display
    Multiple measures display

    Number of Selected Items

    If multiselection is possible, the popover displays the number of items that have been selected. If multiple items have been selected, it is not possible to display the values of all selected items. If you need to display these values, you will have to develop your own solution. For example, you can add a Compare Values or Display Values button at the bottom of the popover. This button is only displayed when multiple items have been selected.

    Related Actions

    You can add related actions at the end of the popover. These related actions may vary depending on the current selection. Related actions can generally be used to do the following:

    • Display more information.
    • Display another type of visualization.
    • Display another dataset.
    • Navigate to another page or app.

    If an action is dedicated to showing more detailed information about the selection, use the View Details label. Actions that are specific to the entire chart or to the app should not be provided in the popover. In this case, it is better to provide them at app level, such as in the app toolbar.

    Examples of popovers with one and three related actions
    Examples of popovers with one and three related actions

    Group of Actions

    Do not display more than four actions in the popover. If more are needed, use in-place navigation.

    Example of in-place navigation
    Example of in-place navigation

    Customization and UI Controls

    The UI controls for customizing the popover are listed below.

    sap.m.responsivePopover:

    1. Use SAPUI5-formatters
 (currency included)
    2. sap.m.ActionListItem

    In-Place Navigation:

    1. sap.m.List with sap.m.StandardListItem type=”Navigation”
    2. sap.m.NavContainer
 for the animation 
(left to right and right to left)
    3. sap.m.Page for the scroll bar
    UI controls for customization – sap.m.responsivePopover
    UI controls for customization – sap.m.responsivePopover
    UI controls for customization – In-place navigation
    UI controls for customization – In-place navigation

    Resources

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

    Elements and Controls

    Implementation

    Cross Feature Popover (SAPUI5 sample)

    Multi-Input Field

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

    Usage

    Use the multi-input field if:

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

    Do not use the multi-input field if:

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

    Responsiveness

    Size S

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

    Size M

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

    Size L

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

    Types

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

    Behavior and Interaction

    Adding Tokens

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

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

    The suggestions dropdown can be wider than the input field itself, but not wider than the current browser window.

    Warning
    The typeahead input feature is not available for Android devices.
    Developer Hint
    Values that are entered can also be tokenized when the user presses ENTER. The app development team can perform a custom validation of the entered data and decide whether a token should be created.
    A token in a multi-input field
    A token in a multi-input field
    A multi-input field with two tokens while editing
    A multi-input field with two tokens while editing
    Information
    For information on how to manage leading and treading whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

    Reviewing Tokens

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

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

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

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

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

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

    Multi-input field - '1 Item' case (desktop)
    Multi-input field - '1 Item' case (desktop)
    Showing the compete item
    Showing the compete item
    Multi-input field - 'n Items' label (desktop)
    Multi-input field - 'n Items' label (desktop)
    Displaying all items
    Displaying all items

    In the input field itself, the user can review tokens using the left or right cursor keys on a desktop, or by swiping to the left or right on a smartphone or tablet. Tokens can be selected by either clicking/tapping them or by pressing Space (selects the focused token).

    Selected token
    Selected token

    Deleting Tokens

    The user can delete tokens by pressing the Backspace or Del button (when selected) on a desktop’s keyboard, or by tapping the Delete icon on a mobile device.

    Using Value Help

    You can enable the value help option to provide a more advanced dialog for finding the relevant business object. Two dialogs can be used at present:

    Value help icon on empty multi-input field
    Value help icon on empty multi-input field
    Select Dialog
    Select Dialog
    Selecting Items
    Selecting Items
    Displaying the selected items in the multi-input field
    Displaying the selected items in the multi-input field
    Value help icon on empty multi-input field
    Value help icon on empty multi-input field
    Value help dialog
    Value help dialog
    Selecting Items
    Selecting Items
    Displaying the selected items in the multi-input field
    Displaying the selected items in the multi-input field

    To give a better indication of the type of data that can be selected, you can exchange the value help icon.

    Custom value help icon
    Custom value help icon

    Filtering

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

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

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

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

    Copying and Pasting Data from a Spreadsheet or Text File

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

    Grouping

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

    The group headers are not interactive.

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

    Multi-input with grouped suggestions
    Multi-input with grouped suggestions
    Multi-input with grouped tabular suggestions
    Multi-input with grouped tabular suggestions
    Multi-input field with grouped tabular suggestions making use of the table's pop-in behavior
    Multi-input field with grouped tabular suggestions making use of the table's pop-in behavior

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

    Styles

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

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

    When an error, warning, or information value state is displayed, the details can be provided as text. The text is shown when the corresponding control has the focus. In addition to plain text, you can include one or several links.

    Error
    Error
    Warning
    Warning
    Success
    Success
    Information
    Information

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

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

    Guidelines

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

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

    • The multi-input field can be used in the grid table, analytical table and tree table as well, as condensed mode is already supported, both for desktop and mobile (tablets).
    Multi-input field in the grid table in condensed mode
    Multi-input field in the grid table in condensed mode
    • In display mode, use a text. Show the texts of the tokens, separated by bullet points. Provide an overflow for all texts that do not fit in one line.
    Recommend display-mode equivalent
    Recommend display-mode equivalent
    Recommended display-mode equivalent with overflow indicator
    Recommended display-mode equivalent with overflow indicator
    Recommended display mode equivalent with overflow opened
    Recommended display mode equivalent with overflow opened

    Properties

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

    Resources

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

    Elements and Controls

    Implementation

    UI Elements

    This article provides an overview of the UI elements used in SAP Fiori. UI elements range from simple controls to complex controls, and include reuse components, smart controls, and controls designed specifically for assistive technologies.
    • Simple controls are the very basic UI elements, such as buttons or links.
    • Complex controls themselves use other controls. For example, a toolbar contains buttons and a smart table contains a title, a toolbar, and items.
    • Reuse components were originally built for a specific use case and line of business. If you have a similar scenario, you may also be able to use them for your app.
    • Smart controls offer additional features to the standard SAPUI5 features, such as OData metadata support. That’s why they are typically used with SAP Fiori elements. However, smart controls can also be used for regular freestyle apps.
    • Controls to support assistive technologies are needed to make the interface accessible to everyone, including people with disabilities.

    Quick Access

    The list below provides an overview of our UI element categories and the UI elements you can expect to find in each one. For tips on when and how to use specific elements, also check the When to Use section under UI Elements in the navigation structure. To get a visual overview of all UI elements, check out the Explore page.


    Action / Navigation

    Action Sheet

    Breadcrumb

    Button

    Icon Tab Bar

    Link

    Smart Link

    Collaboration

    Group Feed Component

    Timeline

    Data Visualization

    3D Viewport

    Analytical Card

    Chart (VizFrame)

    Gantt Chart

    Interactive Chart

    Map

    Micro Chart

    Micro Process Flow

    Network Graph

    Process Flow

    Status Indicator

    Timeline

    Dialog / Popover

    Dialog

    Message Box

    Select Dialog

    Table Select Dialog

    Popover

    Quick View


    Display 

    Avatar

    Avatar Group

    Carousel

    Currency

    Expandable Text

    Formatted Text

    Generic Tag

    HTML

    Image

    Info Bar

    Label

    Lightbox

    Object Display Components

    Progress Indicator

    Status Indicator

    T Account

    Text

    Title

    Token

    Filter

    Filter Bar

    Info Bar

    Token

    Visual Filter Bar

    Variant Management

    Form / Layout / Container

    Carousel

    Dynamic Side Content

    Flexible Grid

    Form / Simple Form

    Icon Tab Bar

    Panel

    Scroll Container

    Smart Form


    Loading / Processing

    Busy Dialog

    Busy Indicator

    Busy State

    Messaging

    Illustrated Message

    Message Box

    Message Page

    Message Popover

    Message Strip

    Message Toast

    Message View

    Table / List / Tree

    Analytical Table (ALV)

    Grid Table

    Responsive Table

    Smart Table

    Tree Table

    Table Personalization

    Grid List

    List

    Smart List

    Tree

    Toolbar

    Chart Toolbar

    Footer Toolbar

    Header Toolbar

    Table Toolbar

    Tree Toolbar


    User Input (Fields, Combo Boxes)

    Input Field

    Multi-Input Field

    Combo Box

    Multi-Combo Box

    Select

    Mask Input

    User Input (Dialog, Visual)

    Select Dialog

    Table Select Dialog

    Value Help Dialog

    Checkbox

    Radio Button

    Rating Indicator

    Slider

    Range Slider

    Step Input

    Switch

    User Input (Date, Time, Calendar)

    Date Picker

    Time Picker

    Date/Time Picker

    Date Range Selection

    Dynamic Date

    Calendar Date Interval

    Calendar

    Planning Calender

    Single Planning Calendar

    User Input (Colors, Texts, Files)

    Color Palette

    Color Palette Popover

    Feed and Notes

    Rich Text Editor

    Search

    Text Area

    Upload Set


    Support for Assistive Technologies

    Invisible Message

    Invisible Text

    Smart Controls

    Dynamic Date

    Smart Field

    Smart Filter Bar

    Smart Form

    Smart Link

    Smart List

    Smart Table

    Reuse Components

    Calculation Builder

    PDF Viewer

    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, a new line is automatically added as soon as a column is selected.

    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 Add button (Add Filter), and remove them by clicking the  button (Remove Filter) 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, a new line is automatically added as soon as a column is selected (only available for the analytical 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

    Chart Toolbar

    The chart toolbar acts as a container for charts.

    The width and height of the chart container are never defined by the app, but are always set by the container itself (as explained in Size of the Chart Container).

    The toolbar is mandatory. Small charts or micro charts, such as dashboards, table cells, and small frames are an exception to this rule. In these cases, the developer must provide a consistent UI to enable action on the chart.

    The toolbar is always placed on top of the chart. It provides actions such as multiple box selection for selecting dimensions, full screen format, personalization actions, and a toggle function for showing and hiding legends.

    Responsiveness

    The chart container uses the sap.m.OverflowToolbar control. It is a container based on sap.m.Toolbar that provides overflow when its content does not fit in the visible area. For more information, please refer to the toolbar overview article (under Responsiveness).

    Chart toolbar – Size L
    Chart toolbar – Size L
    Chart toolbar – Size S
    Chart toolbar – Size S

    Components

    The following content can be part of the chart toolbar. Use only the content your users really need and display them in the order shown below:

    • Title
    • Variant management or perspective switch
    • Business actions (app-specific)
    • Actions for content management
      • Show Legend / Hide Legend
      • Zoom In
      • Zoom Out
      • Settings
    • Minimize / Maximize
    • View switch (between different chart types or between chart and table)
    • Overflow
    Components of the chart toolbar
    Components of the chart toolbar

    Behavior and Interaction

    Business Actions (app-specific)

    If needed, you can define your own actions for the app using transparent text buttons only. If multiple actions are required, sort them, starting with the most important action (= primary action) on the left. You can emphasize the primary action using a ghost button.

    More information:

    Chart toolbar with business actions
    Chart toolbar with business actions
    Chart toolbar with emphasized primary business action
    Chart toolbar with emphasized primary business action

    Title

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

    Use a title if you need the chart toolbar, and if the title of the chart is not indicated in the surrounding area. Note that the title is truncated if there is not enough space.

    Chart toolbar - Title
    Chart toolbar - Title

    Variant Management

    In charts, a variant stores all the settings that define the chart view (for example, the selected dimensions and the sort and filter settings). The variant management control enables users to load, save, and change variants. In most cases, variant management replaces the title.

    Chart toolbar - Variant management
    Chart toolbar - Variant management

    Title and Variant Management

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

    Since using both controls often leads to truncation problems, this pattern is not recommended.

    Chart toolbar - Title with variant management
    Chart toolbar - Title with variant management

    Perspective Switch

    Chart toolbar - Perspective switch
    Chart toolbar - Perspective switch

    The perspective switch is left-aligned in the toolbar. It can be used to switch between different dimensions. We recommend using a select control, but any other dropdown control can be used as well. The perspective switch replaces the title and the variant management control.

    For SAP Smart Business apps, the view incorporates and defines the chart description, the dimension, the measure, and the defaulted chart type. The various views are preconfigured and maintained by an SAP Smart Business administrator.

    Ensure that all switches have a meaningful title. We recommend using a short chart description followed by the dimensions:

    Simple perspective
    Simple perspective

    You also have the option of extending the perspective switch if the app needs to switch between specific subdimensions. The number of dimensions and subdimensions that are needed depends on the app.

    Perspective view with subdimension
    Perspective view with subdimension

    If the app does not need a perspective switch, use the chart title (property: title).

    Chart with title
    Chart with title

    Legend (Generic)

    Chart toolbar with legend button
    Chart toolbar with legend button

    The Legend button (property: ShowLegend) is the first generic action. The user clicks this button to hide or show the chart legend.

    The legend also allows the user to select or deselect data points.

    Zoom In/Zoom Out

    We recommend offering the zoom feature on the chart toolbar. Two icon buttons depicting a magnifying glass are then displayed. When the user clicks the Zoom In or Zoom Out button, the chart zooms accordingly.

    Chart with zoom in/out buttons
    Chart with zoom in/out buttons

    Settings

    You can add a Settings button to the chart toolbar to enable app-specific settings (property: ShowPersonalization). The corresponding popover or dialog must also be implemented by the app team.

    We do not recommend using this feature. If you do choose to use it, exercise caution. Bear in mind that the perspective switch feature already allows preconfiguration of several combinations of dimensions, measures, and chart type selections.

    When viewing charts, users do not usually want to think about which chart types, dimensions, or measures are most suitable in a particular use case. Instead, decide on the most valuable chart/dataset combinations for the end user beforehand and provide users with the most appropriate preconfigured chart view.

    Chart personalization action
    Chart personalization action

    View Switch (Generic)

    Chart toolbar with view switch
    Chart toolbar with view switch

    View switches are right-aligned in the toolbar. They allow the user to switch between different chart types or table layouts. You need to offer the view switch if the chart relies on subtle color differences or color gradients. Users with visual impairments can then use the table view.

    Switches are optional. The buttons can be hidden if there is no need to switch between different charts or tables.

    Be careful when choosing the chart types and the number of switches. For each app, decide which chart types are best suited to visualizing data in the user’s context.

    We recommend using no more than three types of visualization. The sequence of chart type switches is not fixed, but we recommend sorting them by importance and usage within the respective app.

    The segmented button control is used to display the chart types. The control highlights the chart that is currently displayed.

    View Switch – Switch Between Chart and Table

    The view switch allows you to switch easily between tables and charts.

    Some actions are only available in certain views. For example, the Legend icon is only visible in the chart view. If the user selects the table view, the Filter action is visible and the Legend icon is hidden.

    Icon Usage

    Each visualization of a chart is represented by an icon. The icon explorer helps you to find the most appropriate icon.

    Bar chart:
    Bar chart: "SAP-icons" font - Unicode: #e02c - Name: horizontal-bar-chart
    Horizontal bullet chart:
    Horizontal bullet chart: "SAP-icons" font - Unicode: #e215
    Vertical bullet chart:
    Vertical bullet chart: "SAP-icons" font - Unicode: #e216
    Combined column line chart:
    Combined column line chart: "SAP-icons" font - Unicode: #e11f - Name: business-objects-experience
    Stacked bar chart:
    Stacked bar chart: "SAP-icons" font - Unicode: #e183 - Name: horizontal-stacked-chart
    Stacked column 100% chart:
    Stacked column 100% chart: "SAP-icons" font - Unicode: #e180 - Name: full-stacked-column-chart
    Bar chart:
    Bar chart: "SAP-icons" font - Unicode: #e182 - Name: horizontal-bar-chart-2
    Column chart:
    Column chart: "SAP-icons" font - Unicode: #e0ef - Name: vertical-bar-chart
    Pie chart:
    Pie chart: "SAP-icons" font - Unicode: #e015 - Name: pie-chart
    Stacked bar 100% chart:
    Stacked bar 100% chart: "SAP-icons" font - Unicode: #e17f - Name: full-stacked-chart
    Table chart:
    Table chart: "SAP-icons" font - Unicode: #e0bb - Name: table-chart
    Heatmap:
    Heatmap: "SAP-icons" font - Unicode: #e214
    Bubble chart:
    Bubble chart: "SAP-icons" font - Unicode: #e18e - Name: bubble-chart
    Column chart:
    Column chart: "SAP-icons" font - Unicode:  - Name: vertical-bar-chart-2
    Donut chart:
    Donut chart: "SAP-icons" font - Unicode: #e213
    Scatter chart:
    Scatter chart: "SAP-icons" font - Unicode: & #xe18f; - Name: scatter-chart
    Stacked column chart:
    Stacked column chart: "SAP-icons" font - Unicode: #e184 - Name: vertical-stacked-chart
    Map:
    Map: "SAP-icons" font - Unicode: #e185 - Name: choropleth-chart

    Maximize / Minimize

    Chart toolbar with maximize button
    Chart toolbar with maximize button

    In addition to zooming, the app can use the full screen mode of the chart container (property: FullScreen).

    The user can open the chart in a full screen dialog via this toggle button. When the chart is maximized, the    Maximize button is replaced by a corresponding    Minimize button.

    Overflow (Generic)

    See Overflow in the Toolbar Overview article.

    Guidelines

    See the detailed Guidelines section in the Toolbar Overview article.

    Additional Guidelines

    • Think carefully about what actions you really need in the chart toolbar – do not overload the toolbar with actions.
    • Try to put the actions as close to the content as possible.
    • Use appropriate tooltips to label icon buttons in the chart toolbar.

    Resources

    Elements and Controls

    Implementation

    Date Range Selection

    The control for selecting the date range is a single-field input control. Users can enter a localized date range using touch, mouse, or keyboard input, or by selecting a date range in the calendar. They can also navigate directly from one month or year to another.

    Usage

    Use the date range selection if:

    • You need a time range and know that your user is a power user who has to input lots of data. If the keyboard is the primary device used for navigating the app, use two input fields. This allows the user to quickly jump from field to field. By selecting a date in one of the fields, the other field should recognize the information and jump to the same selection.

    Do not use the date range selection if:

    • You want to enter a date and a time. In this case, use the date picker or time picker instead.
    • The user’s primary goal is not to select ranges. If this is the case, use the simple date picker.

    Responsiveness

    The date range selection is fully responsive. It is smaller in compact mode and provides a touch-friendly size in cozy mode. For more information about cozy and compact modes, see the article on content density.

    Date range selection (size S)
    Date range selection (size S)
    Date range selection (size L)
    Date range selection (size L)

    Components

    The date range selection consists of two components: the date range input field (1) and the date range picker (2).

    The two clickable areas of the date range selection on all devices
    The two clickable areas of the date range selection on all devices

    Date Range Input Field

    The user can type the date directly into the input field, or use the date picker. You can also show a prompt text in the field (property: placeholder). The system validates the date and gives the user feedback.

    1. Current day

    2. Currently selected date range

    The dates December 19–22 are selected, and December 5 is shown as the current day
    The dates December 19–22 are selected, and December 5 is shown as the current day

    Date Range Picker

    With the date range picker, the user can see a day view, month view, or year view. The current day and the selected date are highlighted. The calendar week is also visible in the day view. The calendar closes when a final day is selected. The user can click the arrows to view the previous and next days, months, or years (depending on the current view).

    The selected date is shown with a blue background. The current day is indicated with a purple border in the calendar.

    1. Previous month

    2. Quick month selection

    3. Quick year selection

    4. Next month

    5. Day selection

    Clickable areas of the date range selection
    Clickable areas of the date range selection

    Optionally, you can offer a footer with OK and Cancel buttons. This gives users an alternative way of confirming the selected date range.

    Date range picker with 'OK' and 'Cancel'
    Date range picker with 'OK' and 'Cancel'

    Behavior and Interaction

    Selecting a Date Range

    The user can type two dates into the date range input field or click the calendar icon to open the calendar and select a date. These two possibilities work for all devices – desktops, tablets, and smartphones.

    Switch View

    Clicking an arrow shows the next or previous day, month, or year.

    Navigating to the next month
    Navigating to the next month

    Clicking the month shows an overview of all months.

    Opening the month picker
    Opening the month picker

    If the current month is clicked, the user can change the month. When the user selects a month, the view changes to the day view.

    Changing the month navigates back to the date picker. The focus is on the last selected start date.
    Changing the month navigates back to the date picker. The focus is on the last selected start date.

    By clicking the current year, the view changes to the year view. When the user selects a year, the view changes to the day view.

    Opening the year picker
    Opening the year picker

    Selecting a Range

    After the user selects a start date, the dates being hovered over turn light blue to provide visual feedback that a range is being selected. When the user selects an end date, the calendar closes. The range appears in the date input field.

    Selecting the start date
    Selecting the start date
    Selecting the end date
    Selecting the end date

    Entering Single Dates

    The date range selection also allows the user to input single dates. The user can type one date into the input field, or select the same day as a start and end date in the calendar.

    Styles

    Delimiter

    The delimiter visualizes the start and end date. If no delimiter is given, the app uses the one defined for the used locale.

    Placeholder

    If no range is selected, show a placeholder text to indicate the correct format. If no placeholder is defined, the control shows the default locale placeholder format. You can define your own placeholder, but you must also take localized versions into account.

    Date range selection with default placeholder
    Date range selection with default placeholder

    Validation

    Use inline validation to give the user feedback, especially for errors and warnings. Possible validation states are warning, error, success, and information. The date range input field in question is highlighted by a frame in the corresponding color. If the focus is inside the field, an explanation is shown. Ensure that this explanation is as specific as possible.

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

    Visible frame that shows an error when the field is out of focus
    Visible frame that shows an error when the field is out of focus
    Error state with meaningful text; the date range input field is focused
    Error state with meaningful text; the date range input field is focused
    Visible frame that shows a warning when the field is out of focus
    Visible frame that shows a warning when the field is out of focus
    Warning state with meaningful text; the date range input field is focused
    Warning state with meaningful text; the date range input field is focused
    Visible frame that shows that additional information is available
    Visible frame that shows that additional information is available
    Information state with additional information, such as a recommendation
    Information state with additional information, such as a recommendation

    Guidelines

    Display Format

    You can choose whether the displayed texts are to be shown in short, medium, or long format, or in another date format like dd–MM–yyyy. However, other date formats (besides short, medium, and long) should be used carefully due to local dependencies.

    Long display format
    Long display format
    Medium display format
    Medium display format
    Short display format
    Short display format

    Input Types

    The following input types are available. (Note: these examples show German date formats for January 14, 2014.)

    • Unicode CLDR short format: 14.01.14
    • Unicode CLDR medium format: 14.01.2014
    • ISO date format: 2014-01-14
    • ISO date format without delimiters: 20140114
    • Unicode CLDR short format without delimiters: 140114
    • Unicode CLDR medium format: 14012014

    Date Formats

    Long Date Format

    Use the long date format for master list/object list item/title and object header/title. Here are some examples:

    • English (US): January 16, 2022
    • German (DE): 16. Januar 2022
    • Danish (DK): 16. Jan. 2022

    Short Date Format

    Use the short date format for master list/object list item/list of object attributes if space is a concern. For example, you might need to save space if there is a label with the date. Here are some examples of the short date format:

    • English (US): 1/16/22
    • German (DE): 16.01.22
    • Japanese (JP): 22/01/16

    Relative and Medium Date Format

    If appropriate, use a relative format for master list/object list item/list of object status. For example: today, 1 day ago, 2 days ago, and so on up to 6 days ago. After 6 days, use an absolute date with the medium format.

    Use the absolute date with medium format in the corresponding object header in the details area. Do not use the relative format here.

    Responsive Table

    If screen space is at a premium (for example, if there are too many columns), use the short date format within table cells. Otherwise, use the medium format.

    If you need to display the weekday, use the full format. For example:

    • English (US): Sunday, January 16, 2022
    • German (DE): Sonntag, 16. Januar 2022
    • French (FR): dimanche 16 janvier 2022

    Resources

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

    Elements and Controls

    Implementation

    UI Element States

    Overview

    Using the correct state or combination of states for a UI element helps users to recognize possible options and see where they need to take action.

    Depending on the UI element, different types of state are supported:

    • Control states
    • Value states
    • Visual states
    • Additional states

    The table shows the possible states for each type.

    Control States Value States Visual States Additional States
    Enabled
    Disabled
    Hidden
    Read only
    Display only
    Value help only    		 None
    Error
    Warning
    Success
    Information    		 Regular
    Hovered
    Pressed    		 Focused
    Selected
    Required

    Overview of UI element states 

    Control States

    A UI element can have only one control state at any given time.

    Enabled

    “Enabled” is the default state for all UI elements. The UI element is focusable, visible, and – if applicable – editable. The value of the UI element is easy to recognize.

    Developer Hint
    To achieve the enabled state for input controls, set the “editable” property to “true”.
    Enabled button
    Enabled button
    Enabled checkbox
    Enabled checkbox
    Enabled input field
    Enabled input field

    Use the “enabled” state if:

    • A UI element can currently be used.
    • A UI element cannot currently be used, but disabling it is not an option because users might not know how to enable it. In this case, keep the UI element enabled and provide a message if it is used incorrectly.
      Example: Enable a button even if the corresponding action can only be performed if a setting is made on another page or in a completely different subsection on the same page.
    • A UI element is a finalizing action, such as Save, Accept, OK, or Cancel. Finalizing actions are placed on the footer toolbar of a page or dialog.
    • A button on a table toolbar does not depend on items in the table being selected.
      Examples: Column Settings, Sort, Filter, Full Screen, Add
    • A button on a table toolbar depends on items in the table being selected, and one or more of the items currently selected fulfills the requirements for enabling the button.
      Example: Enable Delete on a table toolbar even if the user can delete only some of the items in the current selection.
    • An action is global, such as Share or Print.

    Do not use the “enabled” state if:

    • A UI element cannot currently be used and it would be obvious how enable it. Disable it instead.
    • A UI element cannot be used at all. Hide it instead.
    • A button on a table toolbar depends on items in the table being selected, and none of the items currently selected fulfills the requirements for enabling the button. Disable the button instead.

    Disabled

    Disabled UI elements are visible, but not focusable or editable. Depending on the theme, the value of the UI element might not be recognizable.

    Disabled button
    Disabled button
    Disabled checkbox
    Disabled checkbox
    Disabled input field
    Disabled input field

    Use the “disabled” state if:

    • A UI element cannot currently be used, and it is obvious how enable it.
      Example:
      The user must click a checkbox to add a value in an input field. The input field is placed directly next to or directly below the corresponding checkbox. Disable the input field if the checkbox is not selected, and enable it as soon as the checkbox is selected.
    • A button on a table toolbar depends on items in the table being selected, and the current selection does not include suitable items.
      Examples:

      • Disable Copy if nothing is selected.
      • Disable Compare if fewer than two suitable items are selected.
      • Disable Delete if nothing is selected or if the current selection contains only items that cannot be deleted, such as locked items.

    Do not use the “disabled” state if:

    • A UI element can never be enabled. Hide it instead.
    • It would not be clear why a UI element is disabled. In this case, keep the UI element enabled and provide a message if it is used incorrectly.
    • The input value of a UI element is relevant, and taken into account if a finalizing action is triggered. In this case, users must also be able to read the value. Use the read-only state instead.

    Never disable the checkboxes that are used to select items in a table or list. If an action can’t be executed for some of the selected items, keep the checkbox enabled and display an appropriate message when the action is triggered.


    Hidden

    Hidden UI elements are not visible, not focusable, and not editable. The UI element doesn’t take up any space. If a UI element is hidden at runtime, the freed space is used by subsequent UI elements.

    Use the “hidden” state if:

    • A UI element can never be used (for example, because the role or group assigned to the user doesn’t include the necessary authorization).
    • Hiding the UI element is a meaningful form of responsive behavior.
      Example: A column of a table is not needed on phones.
    • A UI element is not available in the current mode.
      Example: Buttons that are only available in edit mode should be hidden in display mode.
    • A UI element is not available for the current state.
      Examples:

      • Hide Delete on a page in an undeletable state, such as “sent”.
      • Hide Delete as a line-item action for an undeletable item.
    • Parts of the UI are changed based on a setting.
      Example: When changing the setting, hide UI elements that are not available for the new setting.

    Do not use the “hidden” state if:

    • A UI element cannot currently be used, but can be enabled by user actions.
      Examples:

      • A selection does not contain deletable items. In this case, disable Delete.
      • A table was filtered down and currently doesn’t contain deletable items. In this case, disable Delete.

    Information
    Actions can also be hidden by key users (for example, through runtime authoring).


    Read Only

    Read-only UI elements are displayed in edit mode, but are currently not editable. The UI element is visible and focusable. The value can be recognized and selected, but not changed.

    Read-only checkbox
    Read-only checkbox
    Read-only input field
    Read-only input field

    Use the “read only” state if:

    • A page or a part of it is in edit mode, and
      • a UI element is currently not editable or changeable.
      • an input value is relevant and needs to be taken into account when triggering a finalizing action.
      • an input value must be readable.

    Do not use the “read only” state if:

    • A UI element can never become editable. Use alternatives instead (such as text or display only).
    • A page or part of it is in display mode. Use alternatives instead (such as text or display only).

    Display Only

    The display-only state is used for two cases:

    The visualization of display-only UI elements is optimized for reading. The type of UI element does not necessarily need to be recognized. The UI element is not focusable (exception: links), and not editable. Its value is recognizable and shown in full (not truncated). The UI element might also be displayed in a “compressed” format, where the information is displayed differently to the read-only or editable state.

    Developer Hint
    The display-only state is available for only a few UI elements. For most UI elements, you can achieve the same result by replacing them with display elements, such as text.
    Display-only checkbox
    Display-only checkbox

    Use the “display only” state if:

    • A page or part of it is in display mode.
    • An input value is relevant and needs to be taken into account (for example, it is sent on Submit)
    • A page or part of it is in edit mode, and a UI element is never editable (for example, a UI element displaying a generated ID).
    • A link cannot be accessed by the user but the link text contains valuable information.
      Example: A link to a sales order object page shows the sales order number as link text. If the user doesn’t have access to the object page, show the sales order number as plain text.

    Do not use the “display only” state if:

    • A page or part of it is editable and a UI element is currently not editable. Use the read-only state instead.
    • A link cannot be accessed by the user and the link text doesn’t contain valuable information. Hide the link instead.
      Example: A link to a fact sheet shows the link text Fact Sheet (or Details). If the user is not authorized to open the fact sheet, do not show the link at all.

    Value Help Only

    If the control state is “value help only”, the UI element is displayed in edit mode, and is visible and focusable. The value of the UI element is recognizable. The value can be changed, but only with a value help dialog.

    This state is only available for certain user input elements.

    Value-help-only input field
    Value-help-only input field

    Use the “value help only” state if:

    • A UI element can currently be used.
    • User input is limited to specific values, and you don’t want to let users type in values directly.

    Do not use the “value help only” state if:

    • You want to allow free text entry.
    • User input should be limited to specific values, but typing them is faster and more efficient. In this case, work with selects, combo boxes, or input fields with suggestions and validation to limit the user input to the permitted values.
    • The surrounding page (or part of it) is in display mode.

    Value States

    Value states are only available for user input elements. A UI element can have only one value state at any given time. The value states make use of the semantic colors. For more information, see How to Use Semantic Colors.

    None

    “None” (same as “Regular”) is the default state. It means that no value state is applied. Do not change the value state unless you have a reason to do so.

    Input field without value state
    Input field without value state

    Use the “none” state if:

    • There is no reason to use another value state.
    • The user input has not yet been validated.
    • Validation of the user input was successful, without any issues.
    • A message contains non-critical, additional information for users.

    Do not use the “none” state if:

    • User input was validated and a problem occurred. Depending on the severity, use the warning or error state instead.
    • A message contains information about a warning or error.

    Error

    The error state marks a UI element if a validation fails with an error. Errors prevent users from continuing their work.

    Checkbox with error
    Checkbox with error
    Input field with error
    Input field with error

    Use the “error state” if:

    • Users need to be prevented from finalizing the current mode or page.
    • User input failed a validation, and the problem must be fixed before the user can continue.
    • A message contains information about an error.

    Do not use the “error” state if:

    • User input was validated successfully. Do not apply a value state at all.
    • User input was validated and only minor problems occurred. Users can still finalize the current mode or page. Use the warning state instead.
    • The surrounding page (or part of it) is in display mode.

    Warning

    The warning state marks a UI element if a validation identifies a minor problem. Users can carry on working, but might run into an error later on.

    Developer Hint
    In UI5, the warning state is called “Critical”.
    Checkbox with warning
    Checkbox with warning
    Input field with warning
    Input field with warning

    Use the “warning” state if:

    • The current mode or page can be finalized, but doing so might lead to an error later on.
    • User input was validated and a minor problem occurred. It is possible to continue without fixing the problem, but doing so might lead to an error later on.
    • A message contains information about a warning.

    Do not use the “warning” state if:

    • User input was validated successfully. Do not apply a value state at all.
    • User input was validated and a major problem occurred. Users must fix the problem before finalizing the current mode or page. Use the error state instead.
    • The surrounding page (or part of it) is in display mode.

    Success

    The success state marks a UI element if a validation succeeded without errors or warnings.

    Input field - Success state
    Input field - Success state

    Use the “success” state if:

    • A message contains information about a process that was finalized without any issues. Users will need this information later on (for example, values that need to be copied to another app).

    Do not use the “success” state if:

    • A process was finalized successfully and a short notification is enough. In this case, use a message toast instead.
    • The surrounding page (or part of it) is in display mode.

    Information

    The information state marks a UI element to draw attention to the information it provides.

    Input field - Information state
    Input field - Information state

    Use the “information” state if:

    Do not use the “information” state if:

    • The surrounding page (or part of it) is in display mode.
    • User input was validated successfully. Do not apply a value state at all.
    • User input was validated and a major problem occurred. Users must fix the problem before finalizing the current mode or page. Use the error state instead.

    Visual States

    Visual states are handled by the corresponding UI element directly. A UI element can have only one visual state at any given time.

    Regular

    A UI element is shown in the regular visual state if the user is not interacting with it.

    Regular button
    Regular button
    Regular checkbox
    Regular checkbox
    Regular input field
    Regular input field

    Hovered

    The hovered state shows that the cursor of a pointing device (such as a mouse or pen) is currently placed on a UI element that is in an enabled, read-only, or value-help-only state.

    The hovered state is not available if the UI element is used with keyboard and touch devices.

    Button in hovered state
    Button in hovered state
    Checkbox in hovered state
    Checkbox in hovered state

    Do not use the “hovered” state if:

    • You need to provide additional information for a UI element. The hovered state is only available for some interaction devices. When using other devices, the information gets lost.

    Pressed

    The pressed state is displayed when a UI element is activated or remains in an activated state (“toggled”). A UI element is activated if a user clicks it.

    Pressed button
    Pressed button

    Additional States

    Focused

    The focus determines which UI element receives the user input when the user input itself does not supply positioning information (for example, keyboard input).

    Only one UI element can have the focus at any given time.

    The focus is changed by activating another UI element with an input device that provides positioning information (mouse, pen, touch). Clicking an area without a focusable UI element removes the focus until another UI element gets the focus through a user interaction.

    With a keyboard, the focus is changed as follows:

    Key(s) Change in Focus
    Tab Move forward
    Shift+Tab Move backward
    F6 Move the focus forward to the first element of the next group.
    Shift+F6 Move the focus backward to the first element of the previous group.
    Arrow keys Move the focus between items (for example, within lists, tables, calendars, or charts).

    When you move the focus using the keyboard, the newly-focused element does not get activated (“pressed”).


    Initial Focus Position

    When opening a new page, dialog or similar element, make sure that the focus is initially placed at a meaningful element. For example:

    • At the first focusable element below the launchpad shell bar
    • The first editable field
    • The first editable field that requires user input

    Or in general: The element that is likely to be the first one used.

    Focused button
    Focused button
    Focused checkbox
    Focused checkbox
    Focused input field
    Focused input field

    Selected

    The “selected” state shows that the UI element is currently selected. This state is only available for selectable controls, such as checkboxes, radio buttons, or items.

    Developer Hint
    Depending on the UI element, the “selected” state could also be named differently (for example, “Checked”).

    Selected checkbox
    Selected checkbox
    Unselected check box
    Unselected check box

    Required

    The “required” state for a user input element shows that users have to provide an input value. If no value is provided, validation fails.

    Required input field
    Required input field

    Use the “required” state if:

    • A UI element must contain user input.

    Do not use the “required” state if:

    • User input is not mandatory.
    • The UI element is not intended for user input, such as a title.
    • The surrounding page (or part of it) is in display mode.

    Guidelines

    Combining States

    Control States

    Use only one control state at any given time. If several control states need to be combined, use the most restrictive state.

    List of control states in edit mode, from the most restrictive to the least restrictive:

    • Hidden
    • Disabled
    • Display only
    • Read only
    • Value help only
    • Enabled

    In display mode, use only the following control states:

    • Hidden
    • Display only
    • Enabled (for display controls only)

    Visual States

    Use only one visual state at any given time. If several visual states need to be combined, use the one that requires the most user interaction.

    List of visual states, from the most to least user interaction:

    • Pressed
    • Hovered
    • Toggled
    • Regular

    Value States

    Use only one value state at any given time. If several value states need to be combined, use the most severe state.

    List of value states, from the most severe to the least severe:

    • Error
    • Warning
    • Success
    • Information
    • None

    Combining Different Types of State

    • Hidden and disabled UI elements cannot be combined with any other state.
    • Display-only UI elements can be combined with the pressed state (toggle only) and the selected state.
    • Read-only UI elements can be combined with pressed state (toggle only) and with the selected state. In addition, read-only elements can be focused.
    • Value-help-only UI elements can be combined with any visual states. In addition, they can be required and focused.
    • Enabled UI elements can be combined with any visual state, any value state, and any additional state.

    Resources

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

    Elements and Controls

    Implementation

    No links.

    Smart Link

    Intro

    Like the quick view, the smart link triggers a popover from a text link. This popover shows additional information, such as simple object details, and offers links to related apps for the user to take action. The user can choose which links are shown in the popover by selecting them in a separate dialog.
    The smart link is a smart control that uses metadata annotations to offer user-specific navigation. It analyzes the user’s assigned apps and offers only relevant navigation targets.

    When to Use

    Use the smart link if:

    You want to offer direct navigation to a related app. For example:

    • Navigate from a product list to the app for changing the pricing
    • Navigate from a sales order list to the app that shows a customer’s balance

    You want to show a popover with contextual information or navigation. For example:

    • Offer navigation to multiple related apps
    • Display simple object details

    Do not use the smart link if:

    • You want to display more or complex information about an object. Use the object page or charts instead.
    • Access to metadata is not possible, and only a direct link to a website, document or application is needed. Use the standard link instead.
    • You need to structure information in a deeper hierarchy. Use the quick view or a list drilldown instead.

    Components

    The smart link popover contains the following areas:

    1. The header bar of the smart link popover is only visible on mobile devices (see example image for responsiveness, size S).
    2. The title area contains a title and a subtitle. You can also show the title as a link, which can be used to navigate to the corresponding object or fact sheet. You can use the subtitle to show an object ID, for example.
    3. The content area shows object-related information, such as details about a product or contact information. You can use any UI control, based on what best fits your use case.
    4. The link area offers links to all other apps that are relevant for a user role. The link list includes all semantic objects defined for the app, and can also include additional links defined manually by the application development team. The link area can have two states:

    Link area is empty:
    If no links have been selected for the app, or if there are more than 10 links, the link area is initially empty. Instead, the user sees a Define Links button, which opens a dialog for selecting the links to be shown.

    Links are shown:
    As soon as the link area contains links, the button text changes to More Links. This opens the same selection dialog.

    Only the header bar is mandatory (for mobile devices). All the other sections are optional. For example, you might choose to show only a content area or a only a link area, depending on your use case.

    The areas of the smart link (header bar not shown)
    The areas of the smart link (header bar not shown)

    Behavior and Interaction

    The smart link and its popover are always triggered by clicking a text element that appears as a link. You can place this text element in any list, table, or other container. You can also set the link label individually. Clicking outside the popover closes it. If only one link is offered, and there is no additional information, the smart link control navigates directly to the target without opening the popover.

    If the semantic object annotation is not set, the smart link is rendered as sap.m.Text by default. However, you can also opt to render any other control.

    Link Selection Dialog

    Clicking the More Links or Define Links button opens the Define Link List dialog. There, the user can select the app links to be displayed in the link area. The links offered in the selection list are modifiable semantic objects suggested by the smart link control. The app team can remove links from the selection list, change the link texts, or manually add links to any website or app.

    Exception: Within SAP Fiori elements, the links offered in the Define Link List dialog are generated automatically. App teams cannot adapt the list.

    You can switch off the More Links / Define Links option by setting the property enableAvailableActionsPersonalization to “false”. By default, it is set to “true”.

    Smart Links in a Smart Table

    Within a smart table, the link label of the smart link is set automatically using the semantic object annotation. In other words, you can’t change the description. If there are no navigation targets, the smart link is rendered as sap.m.Text.

    Define link list dialog with a list of application links
    Define link list dialog with a list of application links

    Responsiveness

    The responsiveness of the smart link is based on the responsiveness of the popover that overlays the content.

    On desktop devices, clicking anywhere outside the popover closes it.

    On mobile devices, the smart link opens a full screen dialog with a Close icon ( ) on the top right.

    Size S – On smartphones, the smart link overlays the content
    Size S – On smartphones, the smart link overlays the content
    Sizes M/L/XL - Smart link shown in a table on a desktop device
    Sizes M/L/XL - Smart link shown in a table on a desktop device

    Top Tips

    • Check the related apps you offer carefully. Only display those that are relevant for the user.
    • Use meaningful link names in the link area. Do not use the same link name more than once. If necessary, rename the links to suit your context (for example, “Add Product” instead of “Manage Products”).
    • Check the related apps you offer carefully. Only display those that are relevant for the user.
    • Use meaningful link names in the link area. Do not use the same link name more than once. If necessary, rename the links to suit your context (for example, “Add Product” instead of “Manage Products”).

    Related Links

    Elements and Controls

    Implementation

    Text

    The text control is used to display text. It generally contains the text that developers want apps to display (property: text).

    Text used within a form
    Text used within a form

    Usage

    Use the text control if you want to display text inside a form, table, or any other content area. Do not use the text control if you need a label, or vice versa.

    Responsiveness

    The text control is fully adaptive to all screen sizes. You can also set a specific width and overwrite the default value. The resizing behavior depends on the settings that the apps use for the text.

    Wrapping / Truncation

    You can define whether the text should wrap or truncate directly (property: wrapping).

    You can also define how often the text should wrap before it truncates (property: maxLines).

    For more information on using wrapping and truncation, see Wrapping and Truncating Text.

    Text – Maximum line examples
    Text – Maximum line examples

    Hyphenation

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

    Text with hyphenation
    Text with hyphenation
    Text without hyphenation
    Text without hyphenation

    Guidelines

    Empty Indicator Mode

    The emptyIndicatorMode property in sap.m.Text allows app developers to indicate an empty text to users by using an n-dash (“-”). If turned on, an n-dash is rendered when no text is visible. If turned off (default), the behavior is as it is. Depending on the language, the symbol may change.

    Resources

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

    Elements and Controls

    Implementation

    Color Palette Popover

    The color palette popover encapsulates the color palette and the color picker within a popover. You can use it to offer color selectors on toolbars (for example, triggered by a button). The popover allows users to select one of up to predefined 15 colors, or define any other color in a second step if none of the predefined colors fit.

    The color palette popover is also used inside the rich text editor for changing text and background colors.

    Color palette popover
    Color palette popover

    Usage

    Use the color palette popover if:

    • Selecting a color from a predefined palette is the typical case.
    • Users may sometimes need to define their own colors, but in most cases a predefined color or default color is sufficient.
    • Selecting a color is needed as a toolbar action. In this case, use a button or menu button to trigger the color palette popover.

    Do not use the color palette popover if:

    • You want to let users select a color directly on the page (for example, inside a form). Use the color palette or the color picker instead.
    • Users will nearly always define a color of their own, and rarely use the predefined palette. In this case, use the color picker popover instead.

    Responsiveness

    The color palette popover supports cozy and compact content densities. On a phone, the color palette popover turns into a full-screen dialog.

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

    Components

    The color palette popover consists of:

    • A link to select the default color (optional)
    Color palette popover with default color selection
    Color palette popover with default color selection
    Color palette popover containing only a color palette
    Color palette popover containing only a color palette
    • A link that opens a color picker in a dialog (optional). The color picker popover comes in three flavors: simplified, default, and large (property: displayMode). For more information on the three display options, see color picker popover types.
    Color palette popover with the option to set any color
    Color palette popover with the option to set any color
    'More Colors...' opens a color picker dialog
    'More Colors...' opens a color picker dialog
    You can also display a simplified version of the color picker.
    You can also display a simplified version of the color picker.
    • Recent colors (optional). Users can see the last 5 colors they have recently picked. This function helps users to select colors that they have already chosen from the color picker. By default, this feature is visible.
    Color palette popover with 5 recent colors
    Color palette popover with 5 recent colors
    Color palette popover with just one recent color
    Color palette popover with just one recent color

    Behavior and Interaction

    To select a color, users can:

    • Click the Default Color link.
    • Select a color in the predefined color palette or from the recent colors.
    • Click More Colors… to select any other color. This opens the color picker.
    • With the liveChange event, the color change can have an immediate effect and allows app developers to be aware of real-time color changes before they close the popover that contains it.

    On a keyboard, users can navigate within the color palette popover using the arrow keys. Pressing SPACE or ENTER selects a color or triggers a link.

    As soon as a color has been selected, the color palette popover closes automatically.

    Guidelines

    • To trigger the color palette popover, use a button or a value help icon from an input field.
    • Show the selected color in another place (for example, as a color value inside the triggering input field). The color palette popover closes as soon as a color is selected.

    Resources

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

    Elements and Controls

    Implementation

    Color Palette

    You can use the color palette to let users choose a color from a predefined set of colors. The colors are fixed and do not change with the theme.

    Color palette
    Color palette

    Usage

    Use the color palette if:

    • The user needs to select one color from a predefined set of colors.
    • The color set contains between 2 and 15 predefined colors.
    • There is no need to offer additional colors.

    Do not use the color palette if:

    Responsiveness

    The color palette supports cozy and compact content densities.

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

    Components

    • A link to select the default color (optional).
    • The color palette, consisting of 2 to 15 color buttons.
    • Recent colors (optional). Users can see the last 5 colors they have recently picked. This function helps users to select colors that they have already chosen from the color picker. By default, this feature is visible.
    Color palette with all optional features
    Color palette with all optional features
    Color palette with 15 colors and just one recent color
    Color palette with 15 colors and just one recent color

    Behavior and Interaction

    Users can select a color with the left mouse button, the tap gesture, or by pressing SPACE or ENTER on a keyboard. The selected color is not indicated in the control itself.

    With the liveChange event, the color change can have an immediate effect and allows app developers to be aware of real-time color changes before they close the popover that contains it.

    Hovering over a color provides a visual feedback.

    To navigate between different colors on a keyboard, use the arrow keys.

    Visual feedback on hover
    Visual feedback on hover

    Guidelines

    • Show the selected color in another place. The color palette does not visualize the selected color.
    • Label the color palette.
    • If you do not want to show the color palette in-place, consider the color palette popover instead.

    Resources

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

    Elements and Controls

    Implementation

    Rating Indicator

    The rating indicator can be used to rate content or to indicate a rating. It enables users to rate an item on a numeric scale. The most popular scale is 1 (lowest) to 5 (highest).

    Rating indicator
    Rating indicator

    Responsiveness

    The rating indicator runs on all form factors and therefore works on all devices. It is embedded in a container and thus behaves as part of it.

    Rating indicator as part of a form – Size S
    Rating indicator as part of a form – Size S
    Rating indicator as part of a form – Size M
    Rating indicator as part of a form – Size M

    Layout

    Context

    You can use the rating indicator in forms, tables, in a dialog box, or in the filter bar.

    Rating indicator as part of a form
    Rating indicator as part of a form
    Rating indicator in the filter bar / as part of a table
    Rating indicator in the filter bar / as part of a table
    Rating indicator as part of a dialog
    Rating indicator as part of a dialog

    Popover with Details

    In collaborative rating scenarios, the rating indicator shows an average of all ratings. You may show the sum of ratings in brackets behind the rating indicator as a text or link. You may also add a popover that shows the detailed ratings for the average of all ratings.

    Rating details in a popover
    Rating details in a popover

    Behavior and Interaction

    Hover

    When the user hovers over the rating indicator, a different icon or image is shown (property: iconHovered). This is an orange star by default.

    Select

    If enabled for rating, the rating that the user previously selected is shown. When the user performs a rating, an event is triggered.

    Types

    There are two types of rating indicators:

    • Interactive – used for rating an item
    • Disabled

    As the non-interactive state (rating result preview) is not available currently, use the disabled state instead.

    Interactive state
    Interactive state
    Non-interactive state
    Non-interactive state
    Display mode
    Display mode
    Disabled
    Disabled

    Properties

    Rating Symbols

    You can also specify the URLs for the images or icons that are used as rating symbols (property: iconUnselected). Five star symbols are used by default. Although you can use other images or icons, we generally recommend that you use the star symbol. You can only choose 1 symbol for the unselected and 1 for the hovered state.

    Number of Rating Symbols

    You can specify the number of rating symbols (property: maxValue). We recommend using a maximum of 7 symbols, although 5 symbols are preferred.

    Visual Mode of Rating Symbols

    The visual mode defines how float values are visualized: as a half or a full star (property: visualMode). A half star cannot be select by a user. Therefore, it can only be displayed in read-only mode. The main use case for this is to show average ratings.

    Size of Rating Symbols

    The recommended sizes of the image or icon to be displayed are:

    • Large: 2 rem (32 px)
    • Normal: 1.375 rem (22 px) – default
    • Small: 1 rem (16 px)
    • XS: 0.75rem (12px)
    Possible sizes of a rating indicator: L, M, S, and XS
    Possible sizes of a rating indicator: L, M, S, and XS

    Resources

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

    Elements and Controls

    Implementation

    Busy State

    You can set a busy state for each SAPUI5 control. This function adapts to the space available on the UI.

    When to Use

    Use the busy state of the control if:

    • The operation takes more than one second (busy state set at control level)
    • You want to indicate that data is loading on a table or on a list after performing a search or filtering (set the busy state at table or list level).

    Do not use the busy state if:

    • The operation lasts less than one second.
    • You expect several busy states at once. In this case, consider setting the busy state at a higher level or container.
    • You’re loading an app from the launchpad or navigating from an app to another. Use placeholder loading instead (when available in your framework).

    Examples

    Busy page
    Busy page
    Busy buttons
    Busy buttons

    Guidelines

    Avoid showing multiple busy states at once. If you expect multiple busy states on various controls, you can set the busy state on a control or container above.

    In some cases, however, it makes sense to allow multiple busy states. For example, a page could contain a form and several tables that load asynchronously. In this case, it does not make sense to set the busy state at page level until all the data is loaded as the user can start filling out the form which is already available. Response times may vary due to table data retrieval from different services.

    Try to enable as much as possible on one screen, so the user can start working while the rest of the data is being loaded in the background. Set the busy state for those UI elements that will require some time to load.

    Resources

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

    Elements and Controls

    Implementation

    Calendar Date Interval

    The calendar date interval displays a range of days in a single row. The control allows the user to select a single day, multiple days, or a range of days. Content corresponding to the date selection is usually displayed below the control. The user can navigate the date intervals by browsing through them (using the Previous and Next arrows), or by going directly to a specific month or year.

    Compared to the regular date range selection control, this control offers a flexible date range and consumes very little vertical space. You can also adapt the width to fit the available horizontal space.

    When to Use

    • The user simply needs a calendar. Use the calendar instead.
    • The user wants to pick a single date out of a calendar view. Use the date picker instead.
    • The user wants to pick a date and time. Use the date/time picker instead.
    • The user wants to pick a date range out of a calendar view. Use date range selection instead.
    • The user wants to set a dynamic date, such as “last x months”. Use the dynamic date instead.

    Layout

    The date interval control is divided into two main areas: date interval navigation, and date interval display and selection.

    The navigation area contains two arrows (one to the left, one to the right), which allow the user to navigate easily to the previous and next date ranges. This area also contains month and year indicators, which display the currently selected month and year. These indicators trigger the month and year navigation mode of the control.

    The display/selection area is primarily used to display the range of days in the current date interval. You can also display a second row to show the calendar week (property: showWeekNumbers). When the user triggers month or year navigation, a range of months or years is displayed in this section to enable easy interval navigation.

    Schematic visualization of calendar date interval
    Schematic visualization of calendar date interval

    Components

    Current Day

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

    Calendar date interval
    Calendar date interval

    Special Days

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

    Color markings for special days
    Color markings for special days

    Behavior and Interaction

    The behavior and interaction of the calendar date interval control can be divided into two parts: navigation and selection.

    Navigation

    Previous/Next

    The user clicks the Previous or Next arrow to replace the currently displayed date interval with the previous or next date or period. Previous/Next navigation can be used while the user is in selection mode, as well as in month, year, or year interval navigation mode.

    Navigation by Month

    The user triggers month navigation mode by clicking the month link above the date range interval. The currently selected month is highlighted. Clicking a month switches the date range interval to the selected month. The user can browse the months by clicking the Previous and Next arrows.

    Navigation by month
    Navigation by month

    Navigation by Year

    The user triggers year navigation mode by clicking the year link above the date range interval. The currently selected year is highlighted. Clicking a year switches the date range interval to the selected year. The user can browse the years by clicking the Previous and Next arrows.

    Navigation by year
    Navigation by year

    Navigation by Year Interval

    The user triggers the year interval navigation mode by clicking the year interval above the year selection area. The year interval containing the currently selected year is highlighted. Clicking a year interval switches the year range to the selected set of years. The user can browse the year intervals with the Previous and Next arrows.

    Navigation by year interval
    Navigation by year interval

    Selection

    The calendar date interval control can be set up for single day selection, multiple day selection, or date range selection.

    Single day

    The user clicks an unselected day to select that particular day and deselect all previously selected days. Clicking a selected day a second time removes the selection. Only one day can be selected at a time. The selected day is highlighted.

    Selection – Single day
    Selection – Single day

    Multiple days

    The user clicks an unselected day to select that particular day. Clicking a selected day a second time removes the selection. Multiple days can be selected. Selected days are highlighted.

    Selection – Multiple days
    Selection – Multiple days

    Date range

    The user clicks an unselected day to select the start date. Clicking a second unselected day selects the end date. Both the start and end dates are highlighted. The days in between are highlighted in a lighter color. The minimum range is one day and only one range can be selected at a time.

    Selection – Date range
    Selection – Date range

    Responsiveness

    The horizontal space occupied by the control is already minimal, so the responsiveness is limited to the width of the control.

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

    Cozy
    Cozy
    Compact
    Compact

    Examples

    Calendar date interval displaying several weeks
    Calendar date interval displaying several weeks
    Calendar date interval with a selection
    Calendar date interval with a selection

    Related Links

    Elements and Controls

    Implementation

     

    Color Picker Popover

    The color picker popover consists of a color picker within a popover. It enables the user to choose a color from the color spectrum or define it numerically using hex, RGB(A), HSL(A), or HSV(A) values. You can use it to offer color selectors on toolbars (for example, triggered by a button).

    Color picker popover
    Color picker popover

    Usage

    Use the color picker popover if:

    • Selecting any color freely is the typical use case (for example, for user-created content).
    • There is no need for or benefit from a predefined color palette.
    • Selecting a color is needed as a toolbar action. In this case, use a button or menu button to trigger the color picker popover.

    Do not use the color picker popover if:

    • You want to let users select a color directly on the page (for example, inside a form). Use the color palette instead.
    • A predefined palette is beneficial. Use a color palette popover instead.

    Responsiveness

    The color picker popover supports cozy and compact content densities. On a phone, the color picker popover turns into a full-screen dialog.

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

    Layout

    The color picker popover consists of a popover containing a color picker and a toolbar.

    The color picker consists of the following elements:

    • The color picker box for setting lightness and saturation
    • Sliders for setting the hue and transparency (“alpha channel”)
    • Form elements for:
      • Displaying the current and new color settings (Prior to any selection, the default color is white. However, the app developer can set a different predefined color using the setSelected method.)
      • Setting the color as a hexadecimal (hex) value
      • Setting the color as red/green/blue (RGB) value (0 to 255 each)
      • Setting the color as hue/saturation/lightness (HSL) value (hue: 0 to 360 degrees, saturation: 0% to 100%, lightness: 0% to 100%)
      • Setting the transparency (“alpha channel”) value of the color (0.00 for full transparency to 1.00 for opaque)

    The toolbar contains two buttons: OK (emphasized) and Cancel.

    Types

    The color picker popover comes in 3 variants with different levels of complexity:

    • Simplified: The simplified color picker offers basic color manipulation represented only with a hex value, without an alpha value. It shows the current and new color. Text input is only possible for hex values.
    'Simplified' color picker popover
    'Simplified' color picker popover
    • Default: The default color picker allows all settings. It displays input fields either for red / green / blue / alpha or for hue / saturation / lightness / alpha. End users can switch between both sets of input fields.
    'Default' color picker popover
    'Default' color picker popover
    • Large: The large color picker allows all settings and displays all fields at the same time.
    'Large' color picker popover
    'Large' color picker popover

    Behavior and Interaction

    Colors can be selected using mouse/touch or a keyboard:

    • Mouse/touch: Users select a combination of saturation and lightness in the color picker box (click and drag). Hue and alpha values are selected with sliders.
    • Keyboard: The tab key is used to set the focus on the sliders and input fields. Values are entered using the corresponding input controls. The sliders react on arrow keys, page up / page down keys, as well as on home and end keys. The color picker box is not keyboard-enabled.

    The color change can be applied immediately. The OK button confirms the selection of the new color and closes the popover. The Cancel button closes the color picker popover without applying the new color.

    Guidelines

    • To trigger the color picker popover, use a button or a value help icon from an input field.
    • Show the selected color in another place (for example, as a color value inside the triggering input field). The color picker popover closes as soon as a color is selected.
    • Use the simplest color picker popover type that does the job.

    Resources

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

    Elements and Controls

    Implementation

    Tree Toolbar

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

    Usage

    Use the tree toolbar if:

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

    Don’t use the tree toolbar if:

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

    Responsiveness

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

    Components

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

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

    Between the groups, add a separator line.

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

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

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

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

    Behavior and Interaction

    App-Specific Business Actions

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

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

    Title

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

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

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

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

    Variant Management

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

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

    Title and Variant Management

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

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

    Title with variant management
    Title with variant management

    Content Switch

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

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

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

    Use the segmented button and the select control as follows:

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

    For more information, see multiple views for list reports.

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

    Search

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

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

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

    For more information, see Search.

    Search in the tree toolbar
    Search in the tree toolbar

    Create / Add

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

    Insert the new item at the following position:

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

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

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

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

    Edit

    There are several options for editing a tree:

    Edit a Single Item

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

    Editing a single item
    Editing a single item

    Mass Editing

    See: Mass Editing

    Edit the Whole Tree

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

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

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

    Delete / Remove

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

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

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

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

    Cut, Copy, Paste

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

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

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

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

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

    Collapse All, Expand All

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

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

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

    Sort, Filter, Group

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

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

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

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

    For more information, see Table Personalization.

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

    Column Settings

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

    Offer column settings if you need more columns than those that fit on a tablet screen (which is usually five) to fulfill 80% of your main use cases.

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

    For more information, see Table Personalization.

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

    Maximize / Minimize

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

    Export to Spreadsheet

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

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

    Print

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

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

    View Switch

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

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

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

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

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

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

    Overflow

    More information: Toolbar Overview – Overflow.

    Styles

    On the tree toolbar, use the following button styles:

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

    For more information, see Button and Action Placement.

    Guidelines

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

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

    For more information, see UI Element States.

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

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

    For further guidelines, see Toolbar Overview – Guidelines.

    Resources

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

    Elements and Controls

    Implementation

    Quick View

    The quick view is similar to a popover, but has a predefined structure, a fixed set of UI elements, and automatic UI rendering.

    Usage

    Use the quick view if:

    • You want to display a concise overview of an object.
    • You want to display information about, for example, an employee or a company.
    • You can split your information into groups (for example, contact details and company information).

    Do not use the quick view if:

    • You want to provide information in a way other than displaying it in groups.
    • You want to display complex information about an object.

    Responsiveness

    The quick view is based on the popover. It therefore inherits the same basic properties from it and provides the same responsiveness. For more information, see popover.

    Layout

    Generic Quick View

    The figure on the right shows how the content is structured within the quick view. At the top of the content area, you can display an avatar next to the title and subtitle. Additionally, groups and fields are used to structure the information.

    You can use the fallbackIcon property to define a backup icon. This icon is displayed if the initial avatar can’t be loaded.

    Example of a generic quick view
    Example of a generic quick view

    Quick View Examples

    You can create your own quick view element or, as with the two examples below show, there are also basic structures for displaying employee and company information in a quick view.

    Example: Employee quick view
    Example: Employee quick view
    Example: Company quick view
    Example: Company quick view

    Behavior and Interaction

    The quick view is based on the popover. It therefore inherits the same basic properties from it and provides the same interaction. For more information, see popover.

    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

    Expandable Text

    The expandable text control provides access to truncated text. A More/Less link shows or hides the full text. You can expand the text inline or display it in a popover, depending on your use case.

    Expandable texts in a table
    Expandable texts in a table

    When to Use

    Use expandable text if:

    • You need to handle long texts or descriptions inside a responsive table, list or form.
    • You need to provide access to truncated text.

    Do not use expandable text if:

    • You need to display text within UI tables (grid table, tree table, analytical table) or the Gantt chart.
    • You can provide short and meaningful alternatives.
    • The content is critical for the user. In this case, use short descriptions that fit into the available space.

    Components

    • Text
    • More/Less link
    • Optional: Popover

    Behavior and Interaction

    Expanding/Collapsing the Text

    Clicking the More link after the truncated text expands the content inline or in a popover, based on the application settings. When the text is fully visible, the More link is replaced by a Less link.

    Clicking the Less link collapses the content again. If a popover is used, it can be closed by clicking Less (1) or clicking anywhere outside the popover (2).

    Empty State

    The property emptyIndicatorMode behaves as in sap.m.Text. It allows developers to indicate empty texts to users with an n-dash (“-“).

    Inline Text

    Popover

    Responsiveness

    In sizes S, M, L, and XL, the text can be expanded inline or in a popover.

    If you use a popover, the content is displayed in full screen mode on size S.

    Size S – Inline Text

    Expand text with 'More'
    Expand text with 'More'
    Text expanded inline, collapse with 'Less'
    Text expanded inline, collapse with 'Less'

    Size S – Popover

    Expand text with 'More'
    Expand text with 'More'
    Popover text uses full screen, collapse with 'Close'
    Popover text uses full screen, collapse with 'Close'

    Top Tips

    • Adapt the number of characters shown before truncation to fit your use case (default: 100 characters).
    • If using a popover: make sure that the width of the popover always corresponds to the length of the text.
    • If you use the expandable text in a table, set minimal padding to avoid extra white space within the rows.

    Related Links

    Elements and Controls

    Implementation

    Tree Table

    A tree table contains a hierarchical set of data structured in rows and columns and grouped into nodes. The analytical table (also know as ALV) can provide additional details in several non-hierarchical columns per line item. 

    Usage

    Trees are used to display and work with large amounts of hierarchical data. They have a high data density and therefore convey an immediate feeling of complexity. Ideally, you should only show trees with a lot of hierarchical data as a last resort. Try the following instead:

    • Break down the data into manageable chunks and allow the user to navigate or drill down between them.
    • Use charts with drilldown functionality until the amount of data is more manageable.

    Responsiveness

    A tree table is available for desktops and tablets, but not in smartphone sizes. It supports touch devices, but is not optimized for small screens.

    If you use a tree table, note that you have to implement a fallback solution for small screens. This fallback solution does not need to support all use cases.

    Possible fallback solutions are as follows:

    • Use navigation to different pages instead of a tree structure. This works well for structures that are no more than four levels deep.
    • Remove levels until only one or two remain. Replace a single-level tree by a table, and a two-level tree by a grouped table or a split-screen layout.
    • Use filtering instead of a tree structure.

    You can try to create a fallback based on these ideas, but a completely different solution, such as showing charts in a read-only case, might be more appropriate.

    Tree table shown on a desktop
    Tree table shown on a desktop
    Tree table shown on a tablet
    Tree table shown on a tablet

    Types

    Like all SAP Fiori controls, the tree table is shown in compact mode on a desktop and in cozy mode on tablets.

    For a desktop, you can also display even more rows on the same screen height by adding the condensed mode in addition to the compact mode. This renders less white space for each item.

    Note that the condensed content density has always to be set in addition to compact. Do not use condensed on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable and / or unwanted results, e.g. cozy sized controls in condensed sized containers, missing paddings, etc.

    Note that neither compact mode nor condensed mode can be interacted with touch. Even on a desktop with a touch screen, users will have difficulty selecting rows or using controls inside the cells when using their fingers.

    Furthermore, condensed mode is not available for Internet Explorer 9. If condensed mode is to be used, please provide a fallback.

    For more information on cozy and compact modes, see content density.

    Compact Mode

    Tree table – Compact mode
    Tree table – Compact mode

    Condensed Mode

    Tree table – Condensed mode
    Tree table – Condensed mode

    Components

    Column Header

    The column header provides the label for the corresponding column and access to the column header menu.

    Resizing columns works in the following ways:

    • Mouse interaction: Dragging the separator line between two columns (sap.ui.table. Column, property: Resizable). Double-clicking optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable).
    • Touch interaction: The user taps the column header to reveal two buttons: one for showing the column header menu and one for resizing. Drag the latter to resize the column.
    • Keyboard interaction: The width of the focused column header can be increased with Shift+Right and decreased with Shift+Left.

    After resizing a column, the adaptation of the column widths depends on how the column width is set:

    • If column widths are set in pixel-based units (px, em, rem), the corresponding column is adapted and following columns are moved accordingly. The width of all other columns is not affected.
      If all the columns together take up less width than the table control, an empty space is added. If all the columns together take up more width than the table control, a scrollbar appears.
    • If all column widths are set in percentage or “auto”, resizing one column might also lead to the automatic resizing of some or all other columns. The position of the resized column might also be affected. This is done to ensure that the whole table width is used and no white space is added. A scrollbar appears only, if all or most of the columns get very small. To avoid the unintended side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

    Columns can be rearranged by dragging the column header to another position (sap.ui.table.TreeTable, property: enableColumnReordering). Keyboard: the focused column header can be moved by one position to the corresponding direction with Shift+Left / Shift+Right.

    Tree table – Column header
    Tree table – Column header
    Opening the column header menu on touch devices
    Opening the column header menu on touch devices
    Fewer columns than space available
    Fewer columns than space available

    Line Item

    A line item contains a set of cells and provides options for selecting the item.

    To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.TreeTable, property: rowHeight).

    Tree table – Line item
    Tree table – Line item

    In rare cases, show the actions within the line item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. Provide a separate column per action. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

    Tree Column

    The first colum (tree column) provides the hierarchical structure.

    Tree table – Tree column
    Tree table – Tree column

    Expand/Collapse Button

    The expand/collapse button is offered on container nodes to allow the child items of the corresponding container to be shown or hidden.

    Tree table – Collapse
    Tree table – Collapse
    Tree table – Expand
    Tree table – Expand

    Container Node

    A container node is a line item that contains child elements.

    Tree table – Container node
    Tree table – Container node

    Leaf Node

    A leaf node is a line item that does not contain child elements.

    Tree table – Leaf node
    Tree table – Leaf node

    Cell

    Each cell provides one data point. It can contain one of the following controls to display the data point:

    While it is technically possible to also use other controls, doing so could lead to issues in regards to alignment, condensed mode, screen reader support, and keyboard support.

    If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false).

    Tree table – Cell
    Tree table – Cell

    Tree Cell

    A tree cell is a cell inside the tree column. Besides its data point, it provides a collapse/expand button on container nodes, and it indents the different hierarchy levels.

    Tree table – Tree cell
    Tree table – Tree cell

    Column Header Menu

    For the tree column, the column header menu can contain the menu item Freeze and a Filter field, in which the user enters free text.
    For all other columns, only the free text filter is available.

    Tree table – Tree column header menu
    Tree table – Tree column header menu

    Selection Cells

    For multiselection tree tables, the first column contains checkboxes for selecting line items. Besides multiselection, the tree table offers a single-selection mode and also a read-only mode, in which line items are not selectable.

    Tree table – Selection cells
    Tree table – Selection cells

    Select All

    For multiselection tree tables, the column header can contain a checkbox above the selection cells for selecting or deselecting all line items.

    Tree table – Select all
    Tree table – Select all

    Scrollbar

    The tree table allows horizontal and vertical scrolling. You can add any number of line items to the tree table, which uses “lazy loading”.

    To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.TreeTable, property: rowHeight).

    The tree table is optimized to allow faster scrolling within the first 1000 items.

    Tree table – Vertical scrollbar
    Tree table – Vertical scrollbar

    Behavior and Interaction

    Selection

    The tree provides the following possibilities:

    No selection: Items cannot be selected. (property: selectionMode = None)

    Tree table – No selection
    Tree table – No selection

    Single selection: One item in the tree table can be selected. A row selector column is shown. (property: selectionMode = Single)

    Tree table – Single selection
    Tree table – Single selection

    Multiple selection: One or more items can be selected. The tree table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back. The Shift key can be used to select a range.

    For multiple selection, you can choose between two variants.

    • Multi-toggle mode (property: selectionMode = MultiToggle)
    • Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)

    These variants behave differently when the user selects more items than are currently loaded in the front end.

    Multi-toggle

    In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end (keyboard: Ctrl+A). All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

    Multi-selection plug-in

    If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:

    • By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
    • You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
      • The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and a message can appear (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
      • If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets (Keyboard: Ctrl+A).
    • If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.
    Information
    When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

    • The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
    • The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.TreeTable, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

    Tree table – Multiple selection
    Tree table – Multiple selection
    Multi-selection plug-in with a limit
    Multi-selection plug-in with a limit

    Selection Behavior

    An item can be selected in different ways, depending on the configuration of the tree table (sap.ui.table.Table, property: selectionBehavior):

    • Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection tree tables if clicking a row or a cell is not used for anything else.
    • RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
    • RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection tree tables if clicking a row or a cell is not used for another purpose, such as navigation.

    Set the property collapseRecursive to “false” in order to keep the selection on subnodes even after collapsing and expanding the root node.

    Drag and Drop

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

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

    Drag and drop is only available on supporting browsers.

    Drag and drop
    Drag and drop

    Column Header Menu

    Sort

    The column header menu can provide two sort options (sap.ui.table.Column, properties: sortProperty, showSortMenuEntry):

    • Sort Ascending
    • Sort Descending

    The user selects one of these options to sort the corresponding column accordingly (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

    Sort settings in column header menu
    Sort settings in column header menu

    Filter

    The column header menu can provide a search field for entering free text. If the user enters a term in the input field and triggers the search by pressing Enter, the tree is filtered by the tree column and the corresponding value. If no items match the filter values, the filtered tree table may be empty.

    Tree table – Filter
    Tree table – Filter

    Freeze Columns

    The Freeze/Unfreeze option is provided in the column header menu of all columns. Using Freeze on one column freezes all columns from the first one to the selected one.

    Tree table – Freeze
    Tree table – Freeze

    Column Handling

    Show/Hide Columns

    Columns can be shown and hidden. If the tree column is hidden, the following column is the tree column.

    Rearrange Columns

    The user rearranges columns by dragging and dropping the corresponding column header. The tree column is always the first column and cannot be dragged. Keyboard: the focused column header can be moved by one position to the corresponding direction with Ctrl+Left / Ctrl+Right.

    Resize Columns

    Columns are resized as follows:

    • Mouse interaction: The user drags the separator line between two columns (sap.ui.table. Column, property: Resizable). Double-clicking the line optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable). Note that auto-resizing works only if the cells in this column contain one of the following controls: text, label, link, or input.
    • Touch interaction: The user clicks or taps the column header to reveal two buttons: One to show the column header menu, and one for resizing. The user drags the latter to resize the column.
    • Keyboard interaction: The width of the focused column header can be increased with Shift+Right and decreased with Shift+Left.

    Context Menu

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

    When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows (like group headers). Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

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

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

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

    Tree table with context menu
    Tree table with context menu

    Cell Content

    The tree is traditional in that each cell can contain only one data point in one single line.

    Apart from plain read-only text, cells can contain the following:

    While it is technically possible to also use other controls, doing so could lead to issues in regards to alignment, condensed mode, screen reader support, and keyboard support.

    If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false).

    Guidelines

    Filtering

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

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

    Where nodes need to be filtered, keep the following in mind:

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

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

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

    Sorting

    First of all: Is sorting meaningful in your tree? If so, decide on a meaningful default sort order.

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

    Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the tree column.

    To display the current sort state, an icon is shown in the column header of the most recently sorted column. This icon indicates the sort direction (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

    The descending sort order must always be the exact reverse of the ascending sort order. For each column, provide a meaningful sort order. For example:

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

    Loading Data

    To indicate that the table is currently loading items, use the busy state (sap.ui.table.TreeTable, property: busy). Do not show any items or text. As soon as the data has been loaded, remove the busy state and show all items.

    Initital Display

    Think of the initial expand / collapse state of a tree: If your structure contains many items on the root level, it might make sense to collapse the whole tree in the beginning.

    In contrast, if the main items to work with are displayed on a deeper level (e.g. the parent nodes are just some kind of categorization), the tree should be expanded up to the first level where the needed items appear.

    Errors and Warnings

    To indicate that the tree table contains items with errors or warnings, show a message strip above the tree table. On the message strip, provide information on errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

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

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

    Selection

    • We strongly recommend using the multi-selection plug-in. This ensures that all items selected using Select All or as part of a range are included – even if some items were not initially loaded in the front end. This is not the case if you use the multi-toggle option.
    • Do not limit the range selection for the multi-selection plug-in unless you have to.
      • If the dataset is small and/or completely available in the front-end, set the limit property to 0 to enable the Select All option and allow users to select any range.
      • If you have a large dataset, set a limit on the number of selected items to avoid performance issues. Also bear in mind that some actions won’t be helpful if the dataset is too big (for example, a delete operation on 2 million database entries).
    • When setting a limit, also display the corresponding message when the user selects more items at once than the limit allows (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification).
    • For single-selection master-detail scenarios within the flexible column layout, do not show an additional “navigated” indicator.
    • In multiple selection mode, do not show checkboxes in the first data column in the default delivery to avoid confusion.
    • Never disable the selection checkbox. 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.

    Empty Table

    Try to avoid empty tables. If necessary, provide instructions on how to fill the tree table with data.

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

    Add Items

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

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

    Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

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

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

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

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

    There are three options for adding an item. 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 selected node. Show the Save button on the tree 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 tree tables with up to 8 editable columns. Save the new item at 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, tree tables with more than 8 columns). When the user presses Save in the footer toolbar of the create page, navigate back to the tree table.

    Depending on the flow, an item can be in one of three different states:

    • New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
    • Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the corresponding node. Ignore current sort, filter, and grouping criteria to keep the item visible.
    • Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
      • Inline creation: After Save was triggered on the tree toolbar or at page level.
      • Create with dialog: A tree table showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

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

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

    Enabling/Disabling Actions

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

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

    For more details, see UI Element – States.

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

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

    Columns

    Minimize the number of columns. Avoid the need to scroll horizontally in the default delivery. In the first column, show the hierarchical data, which should identify the line item. Choose the name over the ID, but if both are needed, show the name first, then the ID.

    The tree table assigns the same width to each column by default. It is recommended that you overwrite this default to provide optimal space for your content (sap.ui.table.Column, property: width).

    If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the browser window size results in a scrollbar. After resizing a column, a scrollbar appears if the width of the table is not enough to show all columns. If the columns use less space than is available, white space appears on the right side of the last column.

    If you define the column width as a percentage, resizing one column affects the width of several or all columns. Text becomes truncated when the browser window size is reduced. This is done to make sure that all columns together fill the space of the table. A scrollbar appears only in case the automatic change of the column widths is not enough to display all columns. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

    If you define the column width as “auto”, the behavior is the same as for “percentage”. In contrast to percentage, “auto” distributes the columns equally.

    To decide on how to set the column width (pixel/rem/em vs. percent/auto), keep the following tips in mind:

    • For tables with only 2 to 3 columns, use pixel-based units. This ensures that on wide screens the values in the columns are not spread over the whole screen, which improves readability of line items.
    • For tables with many columns, where a horizontal scrollbar is usually needed, use pixel-based units. This avoids unintended side effects when resizing columns.
    • For all other tables, use whatever fits your case better.

    Be cautious with mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it could also cause even more unintended side effects when resizing a column. When using percentage-based widths for one or more columns, think of the possibility to not allow end users to resize columns at all.

    Alignment of Cell Content

    Align column headers according to their cell content:

    • Texts are left-aligned.
    • Numbers (except for IDs), dates, and times are right-aligned.
    • Icons are centered.
    • Micro charts are left-aligned.

    In addition, align amounts with currencies to the decimal point. You can do this with the sap.ui.unified.Currency control.

    Note that most currencies have two digits after the decimal point, but there are exceptions, for example:

    • The Tunisian dinar has three digits.
    • The Japanese yen has no digits.

    In tree tables with mixed currencies, all amounts still have to be aligned to the decimal point.

    To enable positive and negative values to be identified more easily, position the minus sign to the right of the number. It is placed in the same position in every row.

    For more information, see currency.

    Formatting Cell Content

    • Note that there are different locale formats, so show dates, times, and numbers in the correct format for the user’s language/country.
    • If you show both a a text and an ID, consider the requirements for sorting, grouping and filtering:
      • If users need to sort, group, and/or filter by both text and ID, show the text and ID in two separate columns.
      • If users only need to sort, group, and/or filter by either text or ID, show the ID in parentheses after the corresponding text.
    • If the unit of measurement is the same for all rows, show the unit of measurement in the column header. Otherwise, show the unit of measurement within the row.
    • If you want to let users sort, filter, or group by amount and by unit of measure independently, put both in different columns. If you combine them in one column, offer only sorting, filtering, and grouping by amount.

    Tree vs. Table

    Trees are more complex than tables due to their hierarchical view. Users tend to have more problems finding items in hierarchical views than in flat lists, except where the hierarchical view is natural. By natural we mean that every child node should be part of only one parent, and this relationship between the child and parent is clear and well known.

    Do
    Example of an acceptable use of tree tables
    Example of an acceptable use of tree tables
    Do
    A clear parent-child relationship
    A clear parent-child relationship

    When you use trees, you should choose broad hierarchies over deep hierarchies. Deep hierarchies make finding items more complicated. So try to reduce hierarchical levels where possible, especially if the hierarchy is not natural. Ideally, a tree should have a maximum of four levels, the first two of which should contain the most important items.

    Don't
    Avoid unnecessary depth in the hierarchy
    Avoid unnecessary depth in the hierarchy
    Do
    Favor breadth over depth in the hierarchy
    Favor breadth over depth in the hierarchy

    You can use the following methods to reduce hierarchy levels:

    • Avoid single root nodes. A single root node is often used to provide a Select All feature. Since the tree control provides an extra space for a Select All feature, the root node is not usually needed.
    • When you use only two levels, choose a grouped table or grouped ALV over a tree table control. Expand all groups for the default delivery.
    • Container nodes at the top level can usually be replaced by tabs or value pickers.
    • Eliminate unnecessary mid-level containers, for example, by combining redundant ones.
    • Exercise care when using a tree due to its overall complexity. The hierarchical structure of the data does not necessarily mean that a tree control is required.

    Design Concepts

    The tree table can be used to display large amounts of hierarchical data. Unfortunately, tree tables have a high data density and therefore convey an immediate feeling of complexity. Ideally, tree tables with large amounts of data should only be shown if there is no other option. You should instead try the following:

    • Flatten the data. A list, table, or ALV is still complex, but less so than a tree table.
    • Break down the data into manageable chunks. Allow the user to navigate or drill down between them.
    • Use charts with drilldown functionality until the amount of data is more manageable.

    Try to avoid horizontal scrolling in the default delivery.

    Navigation

    To trigger navigation on line item level, choose one of the following options:

    • Use a link for the attribute that identifies the row. Clicking the link triggers the navigation. This is the preferred option.
    • Add the RowActions column and show the navigation arrow (  ) at the end of the row. No column header text is required. The navigation column is fixed and will not scroll away. Users also cannot personalize this column. The navigation arrow triggers the navigation.
      Do not use the RowActions column for actions other than navigation and deletion.

    Special case: Multi-selection in a master-detail scenario
    When a multi-selection table is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case, you can display a “navigated” indicator to show which item is currently open.

    Examples of Incorrect and Correct Usage

    When you use trees:

    • Choose breadth over depth.
    • Emphasize important values. Do not let the user run into a wall of text without guidance. You can use bold text for this.
    • Try to minimize the number of columns, especially if there is a large number of rows.
    • Optimize column width for its initial visible content. Do not automatically adjust column width based on content changes.
    • Do not wrap content, truncate it. End users can easily change the column width to see the full text.
    Don't
    Avoid truncating the initial visible content in the default delivery
    Avoid truncating the initial visible content in the default delivery
    Don't
    Never wrap texts
    Never wrap texts
    • Maintain a fixed layout, except when the user wants to change it.
    • In the default layout, use the tree column for the item name or data that identifies the row. This helps the user to choose between different items.
    • Create a clear and immediately understandable hierarchy. Use clear parent-child relationships. If this is not possible, add a child in different nodes to help the user find the element.
    Do
    Acceptable: repeat entries to optimize finding items
    Acceptable: repeat entries to optimize finding items
    • Consider persisting the layout settings. When a user reopens the app, show the tree table with the same column sizes, column order, and view settings as last defined by this user.
    • Use the Select All feature only if it makes sense. Note that selecting a lot of data also takes time and might not be appropriate for all use cases. For example, a delete operation on two million database entries might not be very helpful in many cases.
    • Set the property collapseRecursive to “false” in order to keep the selection on subnodes even after collapsing and expanding the root node.

    Empty Tree Tables

    Avoid empty tree tables. If necessary, provide instructions on how to fill the tree table with data (sap.ui.table.TreeTable, properties: noDataText, showNoData).

    Examples:

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

    Adapt the texts above if:

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

    Highlight Items

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

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

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

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

    (sap.ui.table.TreeTable, aggregation: rowSettingsTemplate)

    Highlighted items
    Highlighted items

    Drag and Drop

    Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, 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. These are keyboard operable and available on all browsers.

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

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

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

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

    Drop target on an item
    Drop target on an item

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

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

    Don't
    Do not combine rearranging items on the same level with sorting
    Do not combine rearranging items on the same level with sorting

    Visible Alternatives to Drag and Drop

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

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

    Context Menu

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

    The context menu can be triggered for the table, row, or cell. However, we do not recommend using context menus for cells: because the content of a cell is a different touch target than the cell itself, opening a cell context menu via touch is quite hard, even in cozy mode.

    Do not combine context menus with condensed mode: editable controls fill the entire space inside a cell. Because of this, context menus cannot be opened at all with touch or mouse interaction.

    Tables in Object Pages

    In the object page, we advise against using analytical, grid, and tree tables. Instead, use a responsive table and offer navigation to a list report with the table types mentioned above.

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

    Export to Spreadsheet

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

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

    Resources

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

    Elements and Controls

    Implementation

    Tree

    Within SAP Fiori, we distinguish between tree tables and trees. Both usually allow the user to display and work with a hierarchical set of items. While tree tables are usually used for more complex data, trees are generally used for rather basic data. Trees are mostly used in the master list for a master-detail scenario using the flexible column layout and in popovers or dialogs. In certain use cases, they can also be used in the dynamic page layout.

    In the case of tree tables and trees, items that contain additional items are called nodes, while items that do not contain any other items are called leaves. If available, a single topmost node is called a root node. Apart from the hierarchical structure of its nodes and leaves, a tree is quite similar to a list.

    Usage

    Use the tree if:

    • You need to display the key identifier of hierarchically structured items (for example in the first column of the flexible column layout).
    • Selecting one or more items out of a set of hierarchically structured items is a main use case.
    • The hierarchy has a restricted number of levels (up to about 12, depending on the content) and items (around 200).
    • You want to have only one implementation for all devices.

    Do not use the tree if:

    • The main use case is to select one item from a very small number of non-hierarchical items, without viewing additional details. In this case, a select or combo box might be more appropriate.
    • Items are not structured hierarchically. Use a list instead.
    • The hierarchy turns out to have only two levels. In this case, use a grouped list.
    • The hierarchy turns out to be just a categorization based on several details of the item. In this case, an analytical table provides multi-level grouping. Note that the analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You need to display very deep hierarchies with additional data per item. In this case, use a tree table. Note that the tree table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • The structure contains more than around 200 items. In this case, use the tree table. It is optimized for large item sets and provides better performance. Note that the tree table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You need an overview of a large amount of data. In this case, use a chart.

    Check out the table overview to decide which SAP Fiori table is most suitable for your needs.

    Responsiveness

    The tree is like a list containing hierarchical data. It acts as a container for items, with the possibility to expand and collapse nodes. When reducing the width, item texts wrap to ensure that the tree adapts to the new size.

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

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

    Layout

    The title bar (optional) contains the title of the tree. In addition, an item counter and toolbar items can be placed on the title bar.
    The collection of hierarchical items occupies the main part of the tree.

    Schematic visualization of the tree
    Schematic visualization of the tree

    Components

    The title bar consists of a toolbar. The toolbar can contain a title, an item count, and other toolbar items such as actions or view settings, for example.

    The standard tree item consists of:

    • A highlight indicator (optional)
    • An expand/collapse button for nodes
    • A selector in form of a checkbox or a radio button (optional)
    • An icon (optional)
    • A text
    • A counter (optional)
    • Additional buttons with actions such as Edit, Navigate, or Delete (optional)

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

    Standard tree item
    Standard tree item

    Behavior and Interaction (incl. Gestures)

    Tree Level

    Scrolling

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

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

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

    Information
    The “sticky” feature comes with some limitations:

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

    Sticky title
    Sticky title

    Selection Modes

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

    None: Items cannot be selected (sap.m.ListMode.None).
    Beware: Items can, nevertheless, use the sap.m.ListType “navigation” which allows click-handling on specific items. This should only be used when the click triggers a navigation to a corresponding item details page.

    Tree without selectable items
    Tree without selectable items

    Single select master: One item of the tree can be selected. To select an item, click anywhere on the item. Single select master does not add any visual indication to the tree and therefore cannot be differentiated from trees without selection if no item is selected. Therefore, always keep one item selected. For single selection, this is the preferred mode. (sap.m.ListMode.SingleSelectMaster)

    Single selection: Only one item is selected.
    Single selection: Only one item is selected.

    Single select left: One item of the tree can be selected. For this, the tree provides radio buttons on the left side of each line item. Use this selection mode only if clicking on the item triggers something else, such as a navigation. Ideally, always keep one item selected, even in initial state (sap.m.ListMode.SingleSelectLeft).

    Single selection with radio buttons. Use only if row clicks are used for something else, for example navigation.
    Single selection with radio buttons. Use only if row clicks are used for something else, for example navigation.

    Multiple selection: Allows the selection of one or more items. For this, the tree provides checkboxes on the left side of each line item. Each item is selected independently of the others. The Shift key can be used to select a range. Users can (de)select all items using Ctrl+A. Select All should (de)select all items that the user can reach by scrolling. (sap.m.ListMode.MultiSelect).

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

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

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

    Guidelines

    • Never disable the selection checkbox. 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.
    • For single-selection master-detail scenarios within the flexible column layout, use the mode “single select master”. Do not show an additional “navigated” indicator.
    • Avoid the mode “single select left”. It removes the possibility of clicking somewhere on the item to select it. Use it only if it is really necessary to have two different click areas; a small one for a selection, and the rest of the item for something else.
    • If selecting / deselecting all items is important for your app, add a button Select All to the toolbar. Change the button text to Deselect All if all items are selected.

    Multiple selection
    Multiple selection

    Deleting

    To delete single items, use the tree in “delete” mode (sap.m.Tree / sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This adds a Delete  button to each item. Clicking this button triggers the deletion of the corresponding item. Do not use this mode if deleting multiple items at once is the preferred use case. Delete is a mode of the tree and  therefore cannot be used together with single selection or multi selection.

    Tree in 'delete' mode
    Tree in 'delete' mode

    Line Item Level

    Expandable and Collapsible Nodes

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

    Expand/collapse button
    Expand/collapse button

    Highlight an Item

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

    Highlighted item
    Highlighted item

    Navigating

    To allow navigation from an item, set type to “navigation” within the corresponding item (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This will create an indicator at the end of the line (“>”) and the entire item will become selectable. Clicking the line triggers the navigation event. However, clicking a selectable area or an expandable/collapse node does not. Use the navigation event to navigate to a new page containing item details.
    If no navigation is possible, set type to “inactive”.
    Navigation is an item type and therefore cannot be used together with “edit” or in combination with click events for the entire item (“active”).

    Tree items with navigation indicator
    Tree items with navigation indicator
    Navigation indicators can be set per item
    Navigation indicators can be set per item

    Indicate Navigated Item

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

    Navigated item
    Navigated item

    Editing Items

    To allow the user to edit an item, set type to “detail” within the corresponding item (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive). This will create an edit  button at the end of the line. Clicking the button triggers the edit event. Use this event to either open a dialog or a details page where the item can be edited.
    Edit is an item type and therefore cannot be used together with “navigation” or in combination with click events for the entire item (“active”).

    Edit button
    Edit button

    Clicking an Item

    Items as a whole can be clickable. An event is fired by clicking on the item (anywhere except when triggering a selection or when expanding/collapsing a node). Apps can react to the event, such as by opening a dialog (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Active or sap.m.ListType.DetailAndActive).
    Active elements do not have a visual indication and therefore cannot be differentiated from non-active elements.
    “Active” is an item type and  therefore cannot be used together with “navigation” or “edit”. In addition, “active” uses the entire item as a clickable area and thus cannot be used together with single select master.

    Active items
    Active items

    Context Menu

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

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

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

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

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

    Tree - Context menu
    Tree - Context menu

    Drag and Drop

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

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

    Drag and drop is only available on supporting browsers.

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

    Guidelines

    Tree vs. List

    Trees are more complex than lists due to their hierarchical view. Users tend to have more problems finding items in hierarchical views than in flat lists, except where the hierarchical view is natural. By natural we mean that every child node should be part of only one parent, and this relationship between the child and parent is clear and well known.

    Example of an acceptable use of trees
    Example of an acceptable use of trees
    Do
    A clear parent-child relationship
    A clear parent-child relationship

    Broad vs. Deep Hierarchies

    When you use trees, you should choose broad hierarchies over deep hierarchies. Deep hierarchies make finding items more complicated. So try to reduce hierarchical levels where possible, especially if the hierarchy is not natural. Ideally, a tree should have a maximum of four levels, the first two of which should contain the most important items.

    Don't
    Avoid unnecessary depth in the hierarchy
    Avoid unnecessary depth in the hierarchy
    Do
    Favor breadth over depth in a hierarchy
    Favor breadth over depth in a hierarchy

    You can use the following methods to reduce hierarchy levels:

    • Avoid a single root node. It is usually not needed.
    • Container nodes at the top level can usually be replaced by tabs or value pickers.
    • Eliminate unnecessary mid-level containers, for example, by combining redundant ones.
    • Exercise care when using a tree due to its overall complexity. The hierarchical structure of the data does not necessarily mean that a tree control is required.
    Acceptable: repeat entries to optimize finding items
    Acceptable: repeat entries to optimize finding items

    Design Concepts

    The tree can be used to display hierarchical data. Unfortunately, trees convey an immediate feeling of complexity. Ideally, show trees only if there is no other option. You should instead try the following:

    • Flatten the data. A list is still complex, but less so than a tree. A combo box might also fit in some use cases.
    • When only two levels are needed, a grouped list control can be used. This works well, where group nodes are used for categorizing their children and where the group nodes themselves do not need to be selectable.
    • Break down the data into manageable chunks. Allow the user to navigate or drill down between them.
    • Use charts with drilldown functionality until the amount of data is more manageable.

    Design for Performance

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

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

    The actual limits depend on your concrete scenario, including:

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

    Title

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

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

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

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

    If you use a title, be sure to include the following:

    • A title text for the tree.
    • An (optional) item count using the following format: Title (Number of Items). For example, Items (17). Depending on the use case, either count all items or only leaves (for example, if nodes are mainly used for categorization).

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

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

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

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

    Title
    Title
    Title with item count
    Title with item count

    Loading Data

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

    Tree in busy state while loading data
    Tree in busy state while loading data

    Initial Display

    Think of the initial expandable/collapsible state of a tree. If your structure contains many items on the root level, it might make sense to collapse the whole tree in its initial state.

    In contrast, if the most important items are displayed on a deeper level (if, for example, the parent nodes are simply a kind of categorization), the tree should be expanded up to the first level where the most important items immediately appear.

    Errors and Warnings

    To indicate that the tree contains items with errors or warnings, show a message strip above the tree. On the message strip, provide information about errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

    To indicate an error in a single row, see Item States below.

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

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

    Content

    Content Formatting

    To display object names with an ID, show the ID in parentheses after the corresponding object name.

    Place the ID in brackets after the corresponding object name
    Place the ID in brackets after the corresponding object name

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

     

    Examples:

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

    Adapt the texts above if:

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

    Highlighting Items

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

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

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

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

    (sap.m.ListItemBase, property: highlight)

    Highlighted items
    Highlighted items

    Item States

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

    A modified item
    A modified item

    To show that a modified item contains an error, for example within the global edit flow, add the string (Contains errors) to the text of the item and highlight the row accordingly.

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

    To show that an item is locked, add the string (Locked by [name]) to the text of the item.

    A locked item
    A locked item

    To show that an item is in a draft state, add the string (Draft) to the text of the item.

    Item in draft state
    Item in draft state

    Show only one state at any one time.

    Actions

    To trigger actions on items, show the actions on a toolbar above the tree. Do not offer action triggering on multiple items if the tree is expected to have fewer than 10 items in most cases.
    The following actions on single items must always be in-line:

    Delete: Use “Delete” mode (sap.m.Tree / sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This places a Delete  button at the end of each item.

    Items with 'Delete' button
    Items with 'Delete' button

    Navigation: Use the “Navigation” item type (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This places a navigation indicator at the end of the corresponding items. Use this to navigate to a new page containing item details.

    Items with navigation indicator
    Items with navigation indicator

    Edit: Use the “Detail” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail). This places an Edit   icon at the end of the corresponding items.

    Edit button
    Edit button

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

    To trigger actions that are independent of the selection, show the actions on a toolbar above the tree. For example: Add, Collapse All, Expand All, …

    To trigger a default action on the entire item, use the “Active” or “DetailAndActive” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Active). Active items trigger an event when clicked, which can be handled by apps, for example, to open a dialog. Selection and expanding/collapsing a node does not trigger the event, but are handled by the tree. Do not use this for navigation, to switch the line item to an edit state, or to delete the item.
    Active can be combined with edit and delete, but not with navigation. Do not combine active with single selection master.

    Add Items

    For adding items, place an Add or Create text button on the tree 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.

    Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

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

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

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

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

    There are three options for adding an item. In order of priority (most recommended first), these are:

    1. Add the item inline. Create an empty, editable item as the first item of the selected node. Show the Save button on the tree toolbar. This option is recommended for simple scenarios where just a few input fields have to be filled.
    2. Open a dialog for items where up to 8 input fields need to be filled. Save the new item at 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, creating complex objects). When the user presses Save in the footer toolbar of the create page, navigate back to the tree.

    Depending on the flow, an item can be in one of three different states:

    • New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
    • Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the corresponding node. Ignore current sort, filter, and grouping criteria to keep the item visible.
    • Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
      • Inline creation: After Save was triggered on the tree toolbar or at page level.
      • Create with dialog: A tree showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

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

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

    Enabling/Disabling Actions

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

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

    For more details, see UI Element – States.

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

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

    Editing Items

    To edit items, add an Edit button either in-line on the toolbar above the tree. Triggering the button either opens a dialog or navigates to an editable details page.

    For mass editing:

    • Provide multiselection (sap.m.Tree/ sap.m.ListBase, property: mode, value: sap.m.ListMode.MultiSelect).
    • Provide an Edit button on the toolbar above the tree.
    • If several items are selected, triggering the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

    For more details, see mass editing.

    Context Menu

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

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

    Drag and Drop

    Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, 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. These are keyboard operable and available on all browsers.

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

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

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

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

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

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

    Drop targets in between items
    Drop targets in between items

    Visible Alternatives to Drag and Drop

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

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

    Filtering

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

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

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

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

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

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

    Sorting

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

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

    Always sort the tree in a meaningful way when it first loads.

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

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

    Export to Spreadsheet

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

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

    Resources

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

    Elements and Controls

    Implementation

    Grid Table

    A grid table contains a set of data that is structured in rows and columns. It allows the user to scroll in both directions and can handle large numbers of items and columns.

    Usage

    Use the grid table if:

    • The cell level and the spatial relationship between cells are more important than the line item. Examples include spreadsheet analyses and waterfall charts. Note that a grid table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You have to work on more than 1,000 rows. In this case, the grid table is easier to handle. In contrast to the responsive table, the architecture of the grid table is optimized for handling large numbers of items. Note that a grid table is not fully responsive. It is only available for desktop and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • Comparing items is a major use case. In this case, a grid table might be more appropriate than a responsive table. In the grid table, each cell contains only one data point. In contrast, the responsive table is more flexible regarding line items, including the ability to add more data points per cell and also the pop-in function. Both make comparisons more difficult. Note that a grid table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You need an analytical table, but you cannot provide an analytical binding on the technical side. In this case, a grid table will do the work. Note that the grid table provides only one level of grouping, no aggregation options, and is also not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.

    Do not use the grid table if:

    • You need a table. The responsive table is the default table in SAP Fiori. Additional use cases where you might need the responsive table include:
      • The focus is on working on line items, not on cells. The responsive table is optimized for displaying complete items on all devices, such as file browsing and a list of documents you want to act on, like purchase orders and purchase requisitions.
      • Selecting one or several items is the main use case and details are needed to choose the correct item.
      • Line items are independent of each other and no operation across columns is needed.
      • You want to have only one implementation for all devices.
    • The main use case is choosing one item from a very small number of items with no additional details. A select or combo box might be more appropriate.
    • The main use case is choosing one out of several items with only a few details per item. A list might be more appropriate. Pay attention to the layout of the list item to ensure that it has a pleasant appearance.
    • Data needs to be structured in a hierarchical manner. Use a tree table instead. Note that neither the tree table nor the grid table are responsive. You will need to take an adaptive approach by offering an additional UI for smartphones and tablets.
    • You need an overview of a large amount of data. In this case, use charts.
    • You just need it for layout reasons. In this case, use a layout container such as HBox or VBox.
    • You need read-only or editable field-value pairs. Use a form instead. The grid table is not optimized for form-like input navigation.

    Responsiveness

    A grid table is available for desktops and tablets, but not in smartphone sizes. It supports touch devices, but is not optimized for small screens.

    If you use a grid table, note that you have to implement a fallback solution for small screens. This fallback solution does not need to support all use cases.

    You could create a fallback by using a responsive table, but a completely different solution, such as showing charts in a read-only case, might be more appropriate.

    Grid table shown on a desktop
    Grid table shown on a desktop
    Grid table shown on a tablet
    Grid table shown on a tablet

    Layout

    1. Select All – The Select All checkbox selects or deselects all items.
    2. Column header – The column header allows the user to resize and rearrange columns. It also provides access to a menu with column-specific commands.
    3. Selector cells – The selector cells allow the user to select one or more items.
    4. Items – The collection of items, or rows, occupies the main part of the grid table.
    Schematic visualization of the grid table
    Schematic visualization of the grid table

    Components

    A grid table does not consist of other elements. However, it is common to use a toolbar above the grid table.

    The toolbar can contain entry points for the view settings dialog and the table personalization dialog or for the p13n dialog, as well as view switches in the form of a segmented button, and buttons for Add, Edit, and other actions.

    Behavior and Interaction

    A grid table is quite restricted in terms of its content.

    Table Level

    Scroll

    A grid table allows horizontal and vertical scrolling (sap.ui.table.Table, property: navigationMode, value: Scrollbar).

    You can add any number of line items to the grid table, which uses “lazy loading”.

    To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.Table, property: rowHeight).

    The grid table is optimized to allow faster scrolling within the first 1000 items.

    Scrollbar
    Scrollbar

    Select

    Selection Mode

    Selection for a grid table depends on the chosen selection mode. The following options are available:

    No selection: Items cannot be selected. (property: selectionMode = None)

    A non-selection grid table
    A non-selection grid table

    Single selection: One item in the grid table can be selected. A row selector column is shown. (property: selectionMode = Single)

    A single-selection grid table
    A single-selection grid table

    Multiple selection: One or more items can be selected. The grid table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back. The Shift key can be used to select a range.

    For multiple selection, you can choose between two variants.

    • Multi-toggle mode (property: selectionMode = MultiToggle)
    • Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)

    These variants behave differently when the user selects more items than are currently loaded in the front end.

    Multi-toggle

    In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end (keyboard: CTRL+A). All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

    Multi-selection plug-in

    If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:

    • By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
    • You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
      • The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and you can display a corresponding message (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
      • If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets. (Keyboard: CTRL+A)
    • If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.
    Information
    When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

    • The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
    • The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.Table, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

    A multiselection grid table
    A multiselection grid table
    Using the multi-selection plug-in with a limit
    Using the multi-selection plug-in with a limit

    Selection Behavior

    An item can be selected in different ways, depending on the configuration of the grid table (sap.ui.table.Table, property: selectionBehavior):

    • Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection grid tables if clicking a row or a cell is not used for anything else.
    • RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
    • RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection grid tables if clicking a row or a cell is not used for another purpose, such as navigation.

    Compact, Cozy, and Condensed

    Like all SAP Fiori controls, the grid table is shown in compact mode on a desktop and in cozy mode on tablets.

    For a desktop, you can also display even more rows on the same screen height by adding the condensed mode in addition to the compact mode. This renders less white space for each item.

    Note that the condensed content density has always to be set in addition to compact. Do not use condensed on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable and / or unwanted results, e.g. cozy sized controls in condensed sized containers, missing paddings, etc.

    Note that neither compact mode nor condensed mode can be interacted with via touch. Even on a desktop with a touch screen, users will have difficulty selecting rows or using controls inside the cells when using their fingers.

    Furthermore, condensed mode is not available for Internet Explorer 9. If condensed mode is to be used, please provide a fallback.

    For more information on cozy and compact modes, see content density.

    Column Header

    The column header provides the label for the corresponding column and access to the column header menu.

    Columns are resized as follows:

    • Mouse interaction: The user drags the separator line between two columns (sap.ui.table.Column, property: Resizable). Double-clicking the line optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable).
    • Touch interaction: The user taps the column header to reveal two buttons – one to show the column header menu, and one for resizing. The user drags the latter to resize the column.
    • Keyboard interaction: The width of the focused column header can be increased via Shift+Right and decreased via Shift+Left.

    After resizing a column, the adaptation of the column widths depends on how the column width is set:

    • If column widths are set in pixel-based units (px, em, rem), the corresponding column is adapted and the columns that follow are moved accordingly. The width of all other columns is not affected.
      If all the columns together take up less width than the table control, an empty space is added. In case all columns together take up more width than the table control, a scrollbar appears. (sap.ui.table.Column, property: width)
    • If all column widths are set in percentage or “auto”, resizing one column might also lead to the automatic resizing of some or all other columns. The position of the resized column might also be affected. This is done to ensure that the whole table width is used and no white space is added. A scrollbar appears only if all or most of the columns shrink significantly. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

    Columns can be rearranged by dragging the column header to another position (sap.ui.table.Table, property: enableColumnReordering). Keyboard: the focused column header can be moved by one position in the corresponding direction via Ctrl+Left / Ctrl+Right.

    Column header
    Column header
    Opening the column header menu on touch devices
    Opening the column header menu on touch devices
    Fewer columns than space available
    Fewer columns than space available

    Column Header Menu

    For each column, a menu can contain the following menu items (sap.ui.table.ColumnMenu, property: visible):

    • Sort Ascending/Descending (sap.ui.table.Column, property: showSortMenuEntries)
    • Free text filter (sap.ui.table.Column, property: showFilterMenuEntries)
    • Group (sap.ui.table.Table, property: enableGrouping)
    • Freeze from the first to the last specified column (sap.ui.table.Table, property: enableColumnFreeze)

    For each column, the menu can be replaced by an app-specific menu.

    Column header menu
    Column header menu

    Sort

    The column header menu can provide two sort options (sap.ui.table. Column, properties: sortProperty, showSortMenuEntry):

    • Sort Ascending
    • Sort Descending

    The user selects one of these options to sort the corresponding column accordingly (sap.ui.table. Column, properties: sorted, sortOrder, sortProperty).

    Sort settings in column header menu
    Sort settings in column header menu

    Filter

    The column header menu can provide a search field for entering free text (sap.ui.table.Column, properties: filterProperty, showFilterMenuEntries).

    If the user enters a term in the input field and triggers the search by pressing Enter when the focus is on the filter input field, the grid table is filtered by the corresponding column and value (sap.ui.table.Table, properties: filtered, filterProperty, filterValue, filterOperator, sap.ui.table.Column, property: filterType).

    Note that the filter may return zero results, in which case, the table might be empty.

    General recommendations for filtering:

    • If filtering is a main use case, choose the filter bar or any other filtering UI over the built-in free text filter.
    • Only use the free text filter if filtering is a secondary use case and if the filter bar is too heavy.
    Free text filter in column header menu
    Free text filter in column header menu

    Group

    The column header menu can provide the option to group by this column (sap.ui.table.Column, property: enableGrouping).

    A group collects all items with the same value within the corresponding column.

    Group setting in column header menu
    Group setting in column header menu

    If line items are grouped in a column, every group is provided with a collapsible or expandable group header. The header text consists of the name of the value and the number of items in the specific group. Only one grouping level is possible.

    Group header
    Group header

    Once line items have been grouped, the corresponding column is hidden. There is no built-in option to ungroup the grid table again. Therefore, provide a view settings dialog or table presonalization dialog to offer an additional way to group by a column and a way to ungroup the complete table.

    An exception to this is when the table is grouped from the start and should not be ungrouped at all.

    Group headers shown, the corresponding column hidden: no duplicates, but a confusing change
    Group headers shown, the corresponding column hidden: no duplicates, but a confusing change
    Warning
    Note that grouping the grid table is experimental and currently works only on items loaded to the front end. Thus, scrolling down the table leads to data not being grouped as expected.

    Only use this feature if you have just a few line items, all of which are loaded to the front end. If this is the case, consider using a responsive table instead of a grid table.

    Freeze Columns

    The column header menu can provide the option to freeze columns (sap.ui.table.Table, property: enableColumnFreeze). Selecting Freeze freezes all columns up to the one in which the operation was triggered (sap.ui.table. Table, property: fixedColumnCount).

    When Freeze is triggered, the menu item changes to Unfreeze for the corresponding column.

    Freeze setting in column header menu
    Freeze setting in column header menu

    Line Item Level

    A line item contains a set of cells and provides options for selecting the item.

    To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.Table, property: rowHeight).

    Line item
    Line item

    Drag and Drop

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

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

    Drag and drop is only available on supporting browsers.

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

    Context Menu

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

    When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows (like group headers). Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

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

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

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

    Grid table with a context menu
    Grid table with a context menu

    Cell Level

    A cell provides one data point.

    It can contain one of the following controls to display this data point:

    While it is technically possible to also use other controls, doing so could lead to issues in regards to alignment, condensed mode, screen reader support, and keyboard support.

    If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false). Do not wrap.

    Cell
    Cell

    Guidelines

    Data Density vs. Complexity

    The grid table can be used to display large amounts of data. Unfortunately, the grid table has a high data density and therefore conveys an immediate feeling of complexity.

    Only show tables with a lot of data as a last resort. Try the following instead:

    • Break down the data into manageable chunks and allow the user to navigate or drill down between them.
    • Use charts with drilldown functionality until the amount of data is more manageable.

    Try to avoid horizontal scrolling in the default delivery.

    Try to minimize the number of columns, especially if there is a large number of rows.

    Table Title

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

    Use a table title only if the title of the table is not indicated in the surrounding area.

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

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

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

    If you use a table title, show either a title for the table, with or without variant management, or an item count in the following format:

    Items (2,534).

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

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

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

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

    Selection

    Single Selection

    For single-selection master-detail scenarios within the flexible column layout, do not show an additional “navigated” indicator.

    Multiple Selection

    • We strongly recommend using the multi-selection plug-in. This ensures that all items selected using Select All or as part of a range are included – even if some items were not initially loaded in the front end. This is not the case if you use the multi-toggle option.
    • Do not limit the range selection for the multi-selection plug-in unless you have to.
      • If the dataset is small and/or completely available in the front-end, set the limit property to 0 to enable the Select All option and allow users to select any range.
      • If you have a large dataset, set a limit on the number of selected items to avoid performance issues. Also bear in mind that some actions won’t be helpful if the dataset is too big (for example, a delete operation on 2 million database entries).
    • If you set a limit, also display the corresponding message when the user selects more items at once than the limit allows (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification).
    Information
    When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

    • The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
    • The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

    • In multiple selection mode (multi toggle), do not show checkboxes in the first data column in the default delivery to avoid confusion.
    Don't
    Do not add checkboxes to the first data column in the default delivery
    Do not add checkboxes to the first data column in the default delivery
    • Never disable the selection checkbox. 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.

    Loading Data

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

    Grid table in busy state while loading data
    Grid table in busy state while loading data

    Errors and Warnings

    To indicate that the table contains items with errors or warnings, show a message strip above the table. On the message strip, provide information about errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

    To indicate an error in a single row, see Item States below.

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

    Developer Hint
    The sap.m.plugins.DataStateIndicator displays a message strip above the table, which shows binding-related messages.
    Table containing errors and warnings
    Table containing errors and warnings

    Columns – Best Practices

    Minimize the number of columns. Avoid the need to scroll horizontally in the default delivery.

    The grid table assigns the same width to each column by default. It is recommended that you overwrite this default to provide optimal space for your content (sap.ui.table.Column, property: width).

    If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the browser window size results in a scrollbar. After resizing a column, a scrollbar appears if the width of the table is not enough to show all columns. If the columns use less space than available, white space appears on the right side of the last column.

    If you define the column width as a percentage, resizing one column affects the width of several or all columns. Text becomes truncated when the browser window size is reduced. This is done to make sure that all columns together fill the space of the table. A scrollbar appears only in case the automatic change of the column widths is not enough for showing all columns. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum.

    If you define the column width as “auto”, the behavior is the same as for “percentage”. In contrast to percentage, “auto” distributes the columns equally.

    To decide on how to set the column width (pixel / rem / em vs. percent / auto), keep the following in mind:

    • For tables with only 2 to 3 columns, use pixel-based units. This ensures that on wide screens the values in the columns are not spread over the whole screen, which improves the readability of line items.
    • For tables with many columns, where a horizontal scrollbar is usually needed, use pixel-based units. This avoids unintended side effects when resizing columns.
    • For all other tables, use whatever fits your case better.

    Be cautious with mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it could also cause even more unexpected side effects when resizing a column. When using percentage-based widths for one or more columns, think of the possibility to not allow end users to resize columns at all.

    Optimize the column width for its initial visible content, including the column header texts. If this is not possible (for example, if showing the full texts would result in extremely wide columns), let the texts truncate. End users can change the width of the column to read the full text, as needed.

    Maintain a constant column width and avoid adjusting it automatically when the content changes.

    Always keep to one line of text. Do not wrap.

    Don't
    Don't truncate the initial visible content in the default delivery
    Don't truncate the initial visible content in the default delivery
    Don't
    Never wrap texts
    Never wrap texts

    Column Headers – Best Practices

    For each column, provide a label in the column header. In the default delivery, do not truncate the column header texts. Only let the text truncate if showing the full text would make the column too wide. Never wrap the text.

    Content Alignment

    For alignment of cell content, follow the guidelines below.

    Left-align the following: text, IDs, phone numbers, URLs, passwords, and email addresses.

    Left-alignment of text
    Left-alignment of text

    Right-align numbers (except IDs).

    This ensures comparability of numbers and amounts.

    Right-alignment of numbers
    Right-alignment of numbers

    Right-align amounts with currencies to the cell and align them in terms of their respective decimal points.

    This ensures that amounts with different currencies are shown correctly, whether these currencies have 0, 2, or 3 decimals.

    For aligning to the decimal point, use the sap.ui.uinified.Currency control.

    Alignment to decimal point
    Alignment to decimal point

    Right-align dates and times.

    This ensures comparability for most formats and locales.

    Right-alignment of dates
    Right-alignment of dates

    Left-align status information.

    Left-align status information
    Left-align status information

    Center-align icons.

    Left-align micro charts.

    XS micro charts in condensed mode
    XS micro charts in condensed mode

    Content Formatting

    Locale Settings

    Be locale-aware: show dates, times, numbers, and so on in the format corresponding to the user’s locale settings.

    Key Identifier

    Use a bold label or an emphasized link as the key identifier of an item. In the default delivery, show the key identifier in the first column.

    Emphasized link
    Emphasized link

    For strings with IDs, use one of the following options:

    • Show the ID in a separate column. Use this format if users need to sort, group, or filter by both the string and the ID.
    • Show the ID in parentheses after the corresponding string. In this case, you must opt for one criterion for sorting, filtering, and grouping – either the string or the ID. This option is then used for all sort, filter and group actions and can’t be changed later by the user. Use this format only if users don’t need to sort, filter, and group by both the string and the ID.
    Text and ID in two columns – Allows sorting, filtering, and grouping on both
    Text and ID in two columns – Allows sorting, filtering, and grouping on both
    If displayed as a link, use only the text as the link, not the ID
    If displayed as a link, use only the text as the link, not the ID
    Text and ID in one column – Sorting, filtering, and grouping available for either the text or for the ID, but not for both
    Text and ID in one column – Sorting, filtering, and grouping available for either the text or for the ID, but not for both
    Text and ID in one column - If displaying a link, show the whole string as the link (text and ID)
    Text and ID in one column - If displaying a link, show the whole string as the link (text and ID)

    Truncation

    Avoid truncation of typical content in the default delivery (sap.ui.table.Column, property: width). However, since the columns are resizable, do not worry too much if truncation occurs as columns can still be enlarged if necessary.

    To prevent adverse side effects when scrolling vertically, all line items must also have the same height. If you need to decide between truncation and different row heights, choose truncation. Do not wrap.

    Optimize column width for typical content, not all content
    Optimize column width for typical content, not all content

    Number of Links

    Are there too many links? Use subtle links to avoid a wall of links. Standard links are also emphasized more if they are surrounded by subtle links.

    Emphasized links, links, subtle links, and text
    Emphasized links, links, subtle links, and text

    Missing Value

    If there is no value for a cell, leave it blank. Do not display text as N/A.

    Leave empty fields blank
    Leave empty fields blank

    Numbering Items

    In terms of numbering items:

    • If the item number is more like an ID with regard to its description, use ID formatting as described above.
    • In all other cases, use a separate column for the item number.
    Add a separate column for the item number
    Add a separate column for the item number

    Status

    For status information, use semantic colors on the foreground elements.

    For status information on text, use an object status.

    Semantic colors on text
    Semantic colors on text

    Micro Charts

    Use only the following micro charts: Bullet, comparison, stacked bar. When using micro charts, use them in size XS.

    Micro charts in a grid table
    Micro charts in a grid table

    Empty Tables

    Avoid empty grid tables. If necessary, provide instructions on how to fill the grid table with data (sap.ui.table.Table, properties: noDataText, showNoData).

    Examples:

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

    Adapt the texts above if:

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

    Invalid State

    To show an invalid state of the grid table within the list report floorplan, show an overlay on the grid table and the corresponding toolbar (sap.ui.table.Table, property: showOverlay). The overlay prevents user interactions.

    Use this within the list report floorplan if filter settings have been changed but the grid table is has not yet been updated.

    Grid table with invalid data
    Grid table with invalid data

    Item States

    To show that an item has been modified, for example, within the global edit flow, add the string Modified in an additional column with the label Editing Status.

    In the default delivery, add a column directly behind the key identifier.

    A modified item
    A modified item

    To show that a modified item contains an error, for example, within the global edit flow, add the string Contains errors in the Editing Status column and highlight the row accordingly. This string replaces the Modified string.

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

    To show that an item is locked, add a transparent-style button with the corresponding icon and the text Locked by [name] in the Editing Status column.

    A locked item
    A locked item

    To show that an item is in draft state, add a transparent-style button with the text Draft in the Editing Status column.

    Item in draft state
    Item in draft state

    Show only one state at a time.

    Numbers and Units

    Show the unit of measurement in one of the following ways:

    Number and Unit in Same Cell

    The number and the unit are in the same cell. Do this if sorting, filtering, or grouping by the unit of measurement are not needed.

    For amounts, use a currency control to display the concatenated string.

    Number and unit of measurement in one cell
    Number and unit of measurement in one cell

    Number and Unit in Separate Columns

    The number and unit are in separate columns. Do this if sorting, filtering, or grouping by the unit of measurement are a common use case.

    Note that this column can be hidden or moved independently of the column containing the corresponding number. Therefore, be sure to have clear labels for both columns to communicate the dependency.

    Number and unit of measurement in two columns
    Number and unit of measurement in two columns

    Show the unit of measurment on the column header, if the unit of measurement is the same for all rows. If not, show the unit of measurement within the row.

    Drag and Drop

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

    Drop targets in between items
    Drop targets in between items

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

    Don't
    Do not combine rearranging items with sorting
    Do not combine rearranging items with sorting

    Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, 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. These are keyboard operable and available on all browsers.

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

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

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

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

    Context Menu

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

    The context menu can be triggered for the table, row, or cell. However, we do not recommend using context menus for cells: because the content of a cell is a different touch target than the cell itself, opening a cell context menu via touch is quite hard, even in cozy mode.

    Do not combine context menus with condensed mode: editable controls fill the entire space inside a cell. Because of this, context menus cannot be opened at all with touch or mouse interaction.

    Actions

    Multiple Items

    To trigger actions on multiple items, use a mutliselection grid table (sap.ui.table.Table, property: selectionMode, value: MultiToggle). Offer the corresponding actions in the table toolbar.

    Do not offer action triggering on multiple items if the table is generally expected to have fewer than 10 items. In this case, try to use the responsive table instead of the grid table.

    Single Item

    To trigger actions on a single item (sap.ui.table. Table, property: selectionMode, value: Single):

    • Show the actions on the table toolbar.
    • In rare cases, show the actions within the line item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. Provide a separate column per action. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

    To trigger navigation on line item level, choose one of the following options:

    • Use a link for the attribute that identifies the row. Clicking the link triggers the navigation.
    • Add the RowActions column and show the navigation indicator (  ) at the end of the row. The navigation arrow triggers the navigation.

    Special case: Multi-selection in a master-detail scenario
    When a multi-selection table is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case, you can display a “navigated” indicator to show which item is currently open.

    Use the RowActions column only for one or both of the following actions:

    • Navigate to details page ( )
    • Delete ( )

    The RowActions column does not provide a column header text. It is fixed and will not scroll away. Users also cannot personalize this column.

    Navigate to details page
    Navigate to details page

    Single Cell

    To trigger actions on a single cell, create the corresponding click event. Do not use the cell click event if the cell contains interactive controls, such as links.

    Add Items

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

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

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

    Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

    There are three options for adding an item. 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 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.

    Depending on the flow, an item can be in one of three different states:

    • New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
    • Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the table. Ignore current sort, filter and grouping criteria to keep the item visible.
    • Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
      • Inline creation: After Save was triggered on the table toolbar or at page level.
      • Create with dialog: A table showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

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

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

    Enabling/Disabling Actions

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

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

    For more details, see UI Element – States.

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

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

    Editable Content

    For editable content, only use the following controls, and only one control per cell:

    Only these controls are optimized for all viewing modes of the grid table.

    If you need edit mode, change your text controls, such as label, text, link, object status, icons, and currencies, to editable controls as soon as you switch to edit mode, but not before. You can do this by exchanging the controls, for example, from sap.m.Text to sap.m.Input.

    For mass editing items:

    • Provide multiselection.
    • Provide an Edit button.
    • If several items are selected, clicking the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

    For more information, see Mass Editing.

    Interactive controls – In line
    Interactive controls – In line

    View Settings

    There are several ways to show Sort, Filter, and/or Group settings:

    • Column header menu: In all cases, show the corresponding settings in the column header menu.
    • View settings dialog: Simple and more flexible with regard to filter settings. No advantage for sorting. Allows the user to ungroup grouped columns.tables with a medium amount of items.
    • Table personalization dialog: Provides complex options for sorting items by several levels and allows the user to ungroup grouped columns. It also provides a query-builder-like approach for filter settings. The complexity of the options is also its downside. Use the table personalization dialog for tables with a large number of items.
    • If filtering is a main use case, use the filter bar. In this case, avoid offering additional filter settings on the table. If you do, the filter settings on the grid table work only on the result set provided by the filter bar.

    Always be careful when synchronizing the settings in the dialog with the settings from the column header menu.

    Trigger the dialogs in one of the following ways:

    • View settings dialog: Provide several buttons, one for each of these view settings. Each button opens the view settings dialog on the corresponding page.
    • P13nDialog: Provide a settings button, which opens the table personalization dialog containing all pages.

    Use only the view settings you really need. For example, do not offer grouping if it does not support your use case.

    Column header menu with view settings
    Column header menu with view settings
    Table toolbar with triggers for view settings dialog
    Table toolbar with triggers for view settings dialog
    Table toolbar with trigger for table personalization dialog
    Table toolbar with trigger for table personalization dialog

    Be persistent. When reopening the app, show the analytical table in the same view settings (sort/ filter/ group/ aggregation settings) as last defined by this user.

    Sort

    Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the first column in the default delivery.

    To display the current sort state, an icon is shown in the column header of the most recently sorted column. This icon indicates the sort direction (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

    For the default sort settings, sort by the column that identifies the row, which is usually the first column in default delivery.

    Column, sorted ascending
    Column, sorted ascending
    Column, sorted descending
    Column, sorted descending

    The descending sort order must always be the exact reverse of the ascending sort order. For each column, provide a meaningful sort order. For example:

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

    Filter

    To display the current filter state, an icon is shown in the column header of the filtered column (sap.ui.table.Column, properties: filtered, filterProperty, filterValue, filterOperator, defaultFilterOperator, filterType).

    Column, filtered
    Column, filtered

    Group

    To display the current group state, group headers are shown. Show the following text in the group header:

    [Grouping value] – [Item count for the group]

    Group headers
    Group headers

    In general, offer reasonable grouping by default if appropriate. Enable the user to ungroup via the view settings dialog or via the table personalization dialog.

    Personalization

    Only offer personalization if you need more columns than those that fit on a tablet screen, which is usually five, to fulfill 80% of your main use cases.

    Persist the column layout. When a user reopens the app, show the grid table with the same column layout settings as last defined by this user.

    Add, Remove, and Rearrange Columns

    To add, remove, or rearrange columns, use one of the following:

    • The table personalization dialog: It offers some simple settings for column layout. Use this if you have only a few columns to choose from and/or you use the view settings dialog.
    • The p13n dialog: Besides various complex view settings, it also provides settings for column layout. Use this if you have a large number of columns to choose from and/or you use this dialog anyway for view settings.

    In both cases, trigger the dialog via the settings button in the table toolbar. As short cut, use Ctrl+comma.

    You can also use drag and drop to rearrange columns (sap.ui.table.Table, property: enableColumnReordering). If you allow rearranging via drag and drop as well as via a dialog, keep both places in sync.

    Resize Columns

    Resizing columns works differently on touch and non-touch devices.

    • Non-touch devices: Drag and drop the column separator on the right side of the column. Double-clicking the column separator optimizes the width of the column to the data currently loaded into the front end, which is usually about 100 rows.
    • Touch devices: Clicking the column header reveals two buttons: one for opening the column header menu, another one for resizing the column. Drag and drop this second button to resize the column.

    Freeze Columns

    To freeze columns, offer the setting in the column header menu (sap.ui.table.Table, property: enableColumnFreeze). Selecing Freeze on a column freezes all columns from the first one to the one where Freeze is selected. On this column, the menu entry changes from Freeze to Unfreeze.

    Frozen column
    Frozen column

    Highlight Items

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

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

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

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

    (sap.ui.table.Table, aggregation: rowSettingsTemplate)

    Highlighted items
    Highlighted items

    Tables in Object Pages

    In the object page, we advise against using the analytical, grid, and tree tables. Instead, use a responsive table and offer navigation to a list report with the table types mentioned above.

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

    Export to Spreadsheet

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

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

    Paste

    The browser paste function can be used to paste data from the clipboard to the table (Ctrl+V or browser context menu).

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

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

    Properties

    sap.ui.table.Table

    The following additional properties are available for the grid table:

    • The property: width defines the width of the grid table.
    • The property: rowHeight defines the height of each row in the grid table. Since the height required is calculated automatically by the grid table, this property is only needed rarely.
    • The property: columnHeaderHeight defines the height of the column headers. Since the height required is calculated automatically by the grid table, this property is only needed rarely.
    • The property: columnHeaderVisible can be used to hide the column headers. Always show the column headers.
    • The property: showColumnVisibilityMenu provides an additional entry in the column header menu that allows columns to be shown or hidden. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
    • The property: visibleRowCount defines the height of the grid table. Show as many rows as fit on the screen.
    • The property: visibleRowCountMode defines whether the height of the grid table is fixed or automatically calculated based on the space provided by the underlying container. For automatic calculation, make sure that all rows have the same height.
    • The property: minAutoRowCount defines the minimum number of rows that must be shown if the property: visibleRowCountMode is set to “auto”. Show at least three to five rows.
    • The property: firstVisibleRow defines the first row shown in the visible area of the grid table. The grid table is scrolled accordingly.
    • The property: allowColumnReordering is deprecated. Do not use it. Use the property: enableColumnReordering instead.
    • The property: editable does not have a visible effect. Do not use it.
    • The property: enableGrouping turns the experimental grouping on or off. Handle with care.
    • The property: enableCustomFilter changes the filter entry in the column header menu from an edit box to Filter…. Selecting this entry throws an event to which apps can react, for example, by opening a dialog. In general, you should choose the built-in filter over your own implementation. Specifically, keep filtering via the column header menu simple, while offering more advanced options via the table personalization dialog.
    • The property: enableBusyIndicator has not yet been fully implemented. Do not use it.
    • The property: title adds a line of text on top of the grid table. Do not use this. To add a title to the table, use a toolbar.
    • The property: footer adds a short text at the bottom of the table.
    • The property: Busy sets the grid table to busy state. While in busy state, the whole table cannot be used and items cannot be read due to an overlay.
    • The property: Tooltip does not have an effect. Do not use it.
    • The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). Do not use it.

    sap.ui.table.Column

    The following additional properties are available for the column:

    • The property: visible defines whether a column is shown or hidden.
    • The property: name defines the name shown in the column header menu for showing and hiding columns. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
    • The property: headerSpan defines whether one column header is used for one or several columns. To prevent adverse side effects, always use one column header for only one single column. Do not use this property.
    • The property: Tooltip does not have an effect. Do not use it.

    Resources

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

    Elements and Controls

    Implementation

    Select

    The select control (also known as a dropdown) is commonly used to enable users to select an item from a predefined list.

    Usage

    Use the select control if:

    • Users need to select one item exclusively from a short list of options (usually between 2 and 12 items).
    • The values of the option list are of secondary importance and do not need to be displayed right away.

    Do not use the select control if:

    • Users need to choose between two options, such as On or Off and Yes or No. In this case, consider using a switch control instead.
    • Users need to pick one item from a very large set of options. In this case, consider using the combo box instead.
    • You need to display more than one attribute. In this case, consider using the input field with a select dialog or a value help dialog instead.
    • The user needs to search on multiple attributes. In this case, consider using the input field with select dialog or value help dialog instead.
    • Your use case requires all available options to be displayed right away, without any user interaction. In this case, consider using radio buttons or a radio button group instead.
    Information
    For more information on which selection control to choose, see the selection control overview.

    Responsiveness

    The display of the select control depends on the device:

    • On smartphones, the selection list takes up the whole screen.
    • On desktop and tablet devices, it appears as a popover. If there is not enough space to show the option list below the field, it opens above the field.

    Size S

    Select option list in full screen - Size S
    Select option list in full screen - Size S

    Size M

    Select option list – Size M
    Select option list – Size M

    Size L

    Select option list – Size L
    Select option list – Size L

    Size XL

    Select option list – Size XL
    Select option list – Size XL

    Layout

    The select control can be placed in toolbars, such as chart toolbars, footer toolbars, or header toolbars, as well as in forms or tables:

    Components

    Select Trigger

    The trigger to open the option list is either the Select field (1), which also displays the current selection, or an icon (3).

    Option List

    The option list (2) displays all the items available to the user. The selection is always highlighted. Selecting another option from the list moves the highlight to the selected option.

    Full Screen Title Bar for Size S

    Opening the select control on a smartphone brings up the option list in full screen mode. The full screen mode can be closed using the icon on the top right corner (5).

    You need to set a title for the full screen mode (4). We recommend the following format:

    Single selection

    Select [Entity]

    Example: Select Product

    Multi-selection

    Select [Entities]

    Example: Select Products

     

    Anatomy of the select control
    Anatomy of the select control
    Anatomy of the select control - Size S
    Anatomy of the select control - Size S

    Behavior and Interaction

    Clicking

    The Select field always displays the current selection. The user clicks the field to display a list of options to choose from. Once the user selects an option, the list box closes and the selected option is displayed in the field. If there is no Select field but an icon, the user clicks the icon to open the list of options. The currently selected item is always highlighted in the list to help the user identify what has been selected.

    Guidelines

    Option List

    The option list can contain either text-only values or text values with an icon in front. Keep the text values as short as possible.

    Only use icons if they help users better identify or understand the options. To set icons, use the icon property for each list entry.

    Do not disable values. In most cases, it is completely unclear how to enable them. Hide the values instead.

    If you need to indicate that none of the selection options are selected, or you need to allow users to not select an option, offer an appropriate option, such as (Not Selected) or (No Values Selected). Show this option in parentheses and place it at the beginning of the list. For more examples, see the UI text guidelines.

    When using the select control to select filter values: If you need to indicate that all items apply, provide All as an option and place it at the beginning of the list.

    If your use case requires a blank input field instead of (None), use a combo box instead.

    If the select control is placed in a toolbar with an icon as a trigger for sorting, grouping or filtering a set of items, use the texts below for the “not selected” option.

    Sort, Group, and Filter:

    • (Not Sorted)
      Note: In most cases, this option is not necessary; just show the default sort settings instead.
    • (Not Filtered)
    • (Not Grouped)

    For more information about the toolbar, see the toolbar overview.

    Define a default selection whenever possible. If the selected item is not specified, the first one is selected.

    Text only
    Text only
    Icon and text
    Icon and text
    Selection list with '(Not Selected)' option
    Selection list with '(Not Selected)' option

    Label

    The select control can be displayed with or without a label. If the field is attached to another field, you do not need to define a second label.

    Information

    Do not provide a blank value to indicate that nothing is selected.

    Sorting

    The sort option list contains all the items that are available to the user. Choose one of the following styles to order the content:

    Logical: Sort items into a meaningful order. Group related options together and show the most common options first, followed by less common options. Sort the options alphabetically if more than eight select options are available. This helps the user find the right option quickly.

    Example of logical sorting
    Example of logical sorting

    Alphabetical: Sort currencies, names, and similar content alphabetically.

    Example of alphabetical sorting
    Example of alphabetical sorting

    Numeric: Sort numeric values into a sequential order, with the lowest number first.

    Example of numeric sorting
    Example of numeric sorting

    Chronological: Sort time-related information into chronological order, with the most recent first.

    Example of chronological sorting
    Example of chronological sorting

    Width

    The select control is usually used in forms, where the width is determined by the form element or container in which the select control is embedded.

    If you need to restrict the width to a defined value, you can set the width accordingly. However, we do not recommend defining a fixed width. Where possible, use layout containers (such as a form, simple form, or responsive grid layout), and define the width via the layout data property.

    Do not allow the control to auto-adjust based on the selection.

    Information
    If the text length is fixed and doesn’t require localization (for example, currency codes), consider reducing the width.

    Width of the Option List

    By default, the width of the option list adapts to the width of the longest entry. The maximum width of the option list is set to 600 px.

    Maximum width of the option list
    Maximum width of the option list

    Text Wrap in the Option List

    The option list doesn’t support horizontal scrolling. By default, entries that exceed the maximum width of 600 px for the dropdown are truncated. If you expect the dropdown to contain longer entries, we recommend wrapping items in the option list to enable users to read the full text, (property: wrapItemsText). If wrapping is enabled, the text can wrap to multiple lines.

    Option list with wrapped text
    Option list with wrapped text

    Unit of Measurement

    You can use the layout options of the form to can add the unit of measurement (UoM) after select. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

    Developer Hint

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

    Semantic Colors

    Different value states or meanings can be indicated by using semantic colors. The visual states are shown below in their regular state (left) and focused (right). Note that the positive/success state does not show a message on focus.

    For more details on the correct usage, see How To Use Semantic Colors.

    Neutral
    Neutral
    Neutral (focus)
    Neutral (focus)
    Information
    Information
    Information (focus)
    Information (focus)
    Success
    Success
    Success (focus)
    Success (focus)
    Error
    Error
    Error (focus)
    Error (focus)
    Warning
    Warning
    Warning (focus)
    Warning (focus)

    Value State Text

    The select control can display the value state text even if the dropdown is open. This ensures that the value states are shown in all situations and on all devices. When the user opens the dropdown, the value state sticks to the top and does not scroll away. The control also supports multi-line text for the value state.

    Value state text displayed when the dropdown is open
    Value state text displayed when the dropdown is open

    Read-Only

    The select control can be displayed as read-only (property: editable, default = “true”). If the editable property is set to “false”, the value of the select cannot be changed. The control remains focusable, but the background and border are changed to indicate that it is read-only.

    Select in read-only state
    Select in read-only state

    Resources

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

    Elements and Controls

    Implementation

    Infobar

    The infobar is a type of toolbar that appears above a list or panel, and shows filter or selection settings:

    • Filter criteria: The infobar indicates the filter criteria that have been applied for a filter, for example on a table or list. Do not show the infobar if no filter is applied.
    • Selected items: In a multi-select dialog, the infobar shows the number of selected items.
    The infobar is placed above the content and shows the applied filters
    The infobar is placed above the content and shows the applied filters

    Responsiveness

    The bar has the same height, text size, and icon size in both cozy and compact formats. The text inside the bar will be truncated if there’s not enough space.

    Types

    The infobar is shown in the following situations:

    • After a general filter has been applied
    • After the user has selected multiple items in a select dialog

    General Filter

    All applied filters are shown as labels in the infobar.

    Infobar after a filter has been applied
    Infobar after a filter has been applied

    Multiselection

    If the user selects multiple items, the infobar shows the number of selected items. For more information, see select dialog.

    Infobar after multiselection has been applied
    Infobar after multiselection has been applied

    Components

    The infobar is a toolbar that consists of a label on the left side and an icon on the right side.

    The label shows the filter criteria, and the icon selected depends on the use case.

    General Filter and Multiselection

    No icon is shown. The only exception is the Cancel icon, which is used to reset the current filter criteria. For more information, see the responsive table.

    Infobar with optional 'Cancel' icon
    Infobar with optional 'Cancel' icon

    Behavior and Interaction

    The bar can have two active areas: either the entire bar can be active, or if an icon is added, it creates a second active area. We recommend that you use the active behavior for the bar and the icon.

    Bar Area

    When the user clicks the bar, the filter dialog from the view settings dialog is shown. If only one filter is applied, the filter can be changed directly in the detailed filter selection. If more than one filter is applied, the filter dialog shows a list with general filter categories.

    Clicking the infobar with a single filter shows the detailed filter selection
    Clicking the infobar with a single filter shows the detailed filter selection
    Clicking the infobar with multiple filters shows the filter categories
    Clicking the infobar with multiple filters shows the filter categories

    Icon Area

    Cancel: The user clicks the icon to delete the current filter settings. We recommend using the cancel icon.

    States

    The infobar has two states – active and non-active (non-clickable). If set to non-active, the whole bar turns gray and the user cannot interact with it.

    Infobar - Active state
    Infobar - Active state
    Infobar - Non-active state
    Infobar - Non-active state

    Properties

    The infobar is not a separate control. If you want to build an infobar, you need to use the sap.m.Toolbar control. To achieve the infobar design, set the design property of the toolbar to “info”.

    Resources

    Elements and Controls

    Implementation

    Text Area

    The text area is an input control that allows the user to enter several lines of text.

    Usage

    Use the text area if you want users to enter multiple lines of text. If you only want them to enter a single line of text, use the text control instead.

    Responsiveness

    You can set the maximum number of lines to be shown. The amount of text depends on the size of the screen. On smaller screens, the user can scroll down the text area to see the entire text. To indicate that the text continues, the control shows only half of the last line. This also applies for mobile devices.

    Components

    The text area allows the user to enter multiple lines of text.

    Text area – Default
    Text area – Default
    Text area – Active state
    Text area – Active state

    You can also set a placeholder (input prompt), which is inherited from sap.m.InputBase; property: placeholder. The prompt text is displayed when the input field is empty.

    Text area – With placeholder (input prompt)
    Text area – With placeholder (input prompt)
    Text area – Selected state
    Text area – Selected state
    Information
    For information on how to manage leading and trailing white space (blanks) when copying and pasting text into input controls, see removing leading and trailing white space.

    Behavior and Interaction

    Entering and Removing Text

    As soon as the user starts typing, the placeholder disappears. It appears again when the user removes all the content from the text area.

    You can also limit the number of characters a user can enter. In this case, the text area prevents the user from adding more characters than the maximum value defined (property: maxLength).

    Text area – Limited
    Text area – Limited

    Making Text Non-Editable

    You can set the text area to non-editable (property: editable). This mode still allows the user to scroll to the text that is currently hidden.

    Text area – Read-only
    Text area – Read-only

    Disabling Text

    You can also set the text area to disabled. In this case, the user cannot edit or scroll (property: enabled).

    Text area – Disabled state
    Text area – Disabled state

    Growing Behavior

    The text area control offers a growing property. It gives the control the ability to automatically grow and shrink with its content while the user is typing.

    The maximum height of the text area is configurable. Define the height to reflect the space where the control will be located.

    Growing text area: The text is aligned to the top of the text area. A new line is added to the bottom of the text area.
    Growing text area: The text is aligned to the top of the text area. A new line is added to the bottom of the text area.

    Text Area Counter

    General Information

    If you have set a character limit for the text box (property: maxLength), you can use the text area counter to show a character count (remaining characters, characters over the limit).

    To turn on the counter, set the property showExceededText to true. The user can then see all inserted characters, including those that are over the limit.

    Basic Interactions

    The number of characters allowed is displayed below the text area, aligned to the right. A label indicates how many characters are left.

    When the characters are over the limit:

    • Тhe user can continue typing and the text area changes to a warning state.
    • The value of the counter changes.

    When the user pastes copied text, characters that are over the limit are selected automatically. The user can delete any excess characters by pressing Delete or Back on the keyboard (or virtual keyboard for phones and tablets).

    Text area counter - Default state (within the limit)
    Text area counter - Default state (within the limit)
    Text area counter components
    Text area counter components

    Text Area Counter - Basic Interactions

    Developer Hint
    The counter comes with a preset value state for the text area, which controls the appearance of the text area when the text exceeds the character limit. This preset helps the app developer to define the target behavior of the control.

    The predefined value state is a warning state.

    If the app developer sets additional value states, and the text exceeds the limit, the value states are displayed in the following order (highest to lowest priority):

    • Additional error state available: This results in a higher priority (error + warning = error). If an error state is set, the text area is shown in an error state. When the error is fixed, the text area returns to the warning state until the character count is within the limit.
    • Additional warning state available: An additional warning state has the same priority as the counter warning state (warning + warning = warning). The text area stays in the warning state until all of the issues are fixed. The warning state set by the developer has the higher priority.
    • Additional success state available: In this case, the warning state has higher priority (success + warning = warning). Once the text count is within the limit, the text area shows the success state.

    Styles

    As with any other input control, you can validate the fields and show the result as a value state of the control (property: valueState). Possible value states are error, warning, success, information, or neutral (none).

    For more information, see How To Use Semantic Colors and Form Field Validation.

    Text area – Warning state
    Text area – Warning state
    Text area – Error state
    Text area – Error state
    Text area - Success state (with thinner border)
    Text area - Success state (with thinner border)
    Text area - Information state
    Text area - Information state

    Guidelines

    • As with other input fields, use a label. For exceptions regarding label usage, see the Exceptions section of the Label article.
    • The placeholder does not substitute a label. It can be used to give an additional hint, but should not repeat the label in long format.
    • If you want to use the text area with a fixed text length (property: maxLength), for example, inside a form, use text beside the text area to count down the number of remaining characters while the user is typing.
    • If you are applying the growing behavior of the text area, bear in mind that its maximum height should not exceed the height of the screen.

    Saving Forms with a Text Area Counter

    If a text exceeds the limit for the text area, there are two options for saving the form:

    • The form can be saved, but only contains the text within the character limit. If you follow this approach, inform the user that only part of the text will be saved. In this case, we strongly recommend setting the text area state to “warning” to indicate that there is a problem with the text.
    • The form cannot be saved until the user edits the text and the character count is within the limit. In this case, we strongly recommend setting the text area state to “error”.

    Properties

    • You can provide a width by specifying the average character width (property: cols).
    • You can define the height of the text area by specifying the number of lines of text (property: rows). You can also set the height of the text area (property: height), which overrides the rows property.
    • You can define the type of wrapping for the text area (property: wrapping) as soft, hard, or off.
    • sap.m.TextArea has a growing property that enables the height of the text area to change dynamically while the user is typing.
    • sap.m.TextArea can show a count for the number of permitted characters, and allow users to type/paste text over the limit (property: showExceededText). This property determines whether characters that exceed the character limit are visible.
      • If this property is set to false, the user is not allowed to exceed the number of characters set in the maxLength property.
      • If this property is set to true, characters exceeding the maxLength value are selected on paste, and the counter below the input field displays the number of characters that are over the limit.

    Resources

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

    Elements and Controls

    Implementation

    Table Toolbar

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

    Usage

    Use the table toolbar if:

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

    Do not use the table toolbar if:

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

    Responsiveness

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

    Components

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

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

    Between the groups, add a separator line.

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

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

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

    All possible components in the correct order
    All possible components in the correct order

    Behavior and Interaction

    App-Specific Business Actions

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

    Table toolbar with app-specific buttons
    Table toolbar with app-specific buttons

    Title

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

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

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

    Title with item counter in the table toolbar
    Title with item counter in the table toolbar

    Variant Management

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

    Variant management in the table toolbar
    Variant management in the table toolbar

    Title and Variant Management

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

    Since using both controls often leads to truncation problems, this pattern is not recommended.

    Title with variant management
    Title with variant management

    Content Switch

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

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

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

    Use the segmented button and the select control as follows:

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

    For more information, see multiple views for list reports.

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

    Search

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

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

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

    For more information, see Search.

    Search in the table toolbar
    Search in the table toolbar

    Edit

    There are several options for editing a table:

    Edit a Single Item

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

    Editing a single item
    Editing a single item

    Mass Editing

    See: Mass Editing

    Edit the Whole Table

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

    See also: Object Handling (Create, Edit, Delete)

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

    Create / Add

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

    See also: Object Handling (Create, Edit, Delete).

    Table toolbar with 'Create' button
    Table toolbar with 'Create' button
    Table toolbar with 'Add' button
    Table toolbar with 'Add' button

    Delete / Remove

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

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

    See also: Object Handling (Create, Edit, Delete)

    Table toolbar with 'Delete' button
    Table toolbar with 'Delete' button
    Table toolbar with 'Remove' button
    Table toolbar with 'Remove' button

    Show Details / Hide Details

    Based on the responsive behavior of a table, data can be shown in the pop-in area. With the Show Details / Hide Details function, users can switch between a full data set or a reduced data set.

    This function is part of the view settings group and is displayed at the first position of this group.

    For more information, see Smart Table.

    'Show Details' function to show all data in pop-in area
    'Show Details' function to show all data in pop-in area
    'Hide Details' function to reduce data in pop-in area
    'Hide Details' function to reduce data in pop-in area

    Sort, Filter, Group

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

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

    Always use only the view settings you really need. For example, do not offer grouping if it does not support your use case.

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

    For more information, see Table Personalization.

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

    Column Settings

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

    Offer column settings if you need more columns than those that fit on a tablet screen (which is usually five) to fulfill 80% of your main use cases. Before you do this, try to reduce the number of columns, for example, by using several lines per column or by using the pop-in feature.

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

    For more information, see Table Personalization.

    Table toolbar with 'Column Settings' button
    Table toolbar with 'Column Settings' button

    Export to Spreadsheet

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

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

    Print

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

    Table toolbar with 'Print' button
    Table toolbar with 'Print' button

    Maximize / Minimize

    To allow the user to show the table in full screen mode (property: ShowFullScreenButton), show the   Maximize button.  The user can exit the full screen by clicking the   Minimize button.

    Table toolbar with 'Maximize/Minimize' button
    Table toolbar with 'Maximize/Minimize' button

    View Switch

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

    Switches are optional and do not have to be provided if there is no need to switch between different charts or tables.

    Define the number of chart types and switches with care. Offer only chart types that are meaningful for visualizing the respective data and that best assist the user. Ideally, offer no more than three types of visualization.

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

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

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

    Overflow

    See: Toolbar Overview – Overflow.

    Styles

    On the table toolbar, use the following button styles:

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

    For more information, see Button and Action Placement.

    Guidelines

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

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

    For more details, see UI Element States.

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

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

    For further guidelines, see Toolbar Overview – Guidelines.

    Resources

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

    Elements and Controls

    Implementation

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

    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.

    Items can be navigated in all directions using the Arrow keys. To skip several rows, Page Up and  Page Down can be used. To move the focus to the first / last item use the Home and End keys.

    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. Users can (de)select all items using Ctrl+A. Select All must (de)select all items that the user can reach by scrolling. Try to avoid combining multi selection with navigation.
    An unselected and a selected item in
    An unselected and a selected item in "multi selection"
    Guidelines

    • Never disable the selection checkbox. 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.
    • 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.
    • For single-selection master-detail scenarios within the flexible column layout, use the mode “single select master”. Do not show an additional “navigated” indicator.
    • Avoid the mode “single select left”. It removes the possibility of clicking somewhere on the item to select it. Use it only if it is really necessary to have two different click areas; a small one for a selection, and the rest of the item for something else.
    • If selecting / deselecting all items is important for your app, add a button Select All to the toolbar. Change the button text to Deselect All if all items are selected.

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

    Loading Data

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

    Empty Grid Lists

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

    Examples:

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

    Adapt the texts above if:

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

    Context Menu

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

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

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

    Group

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

    A grouped grid list
    A grouped grid list

    Guidelines

    Actions

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

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

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

    To trigger actions on a single item only (sap.m.GridList, property: mode, value: sap.m.ListMode.SingleSelectMaster), the action can also be shown within the item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every item and thus use a lot of screen real estate, only do this for one or two actions at most. In this case, show the action trigger near the content to which it belongs. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

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

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

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

    Design for Performance

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

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

    The actual limits depend on your concrete scenario, including:

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

    Add Items

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

    Depending on the flow, an item can be in one of three different states:

    • New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
    • Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the grid list. Ignore current sort, filter, and grouping criteria to keep the item visible.
    • Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
      • Inline creation: After Save was triggered on the toolbar or at page level.
      • Create with dialog: A grid list showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

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

    Export to Spreadsheet

    Mass Editing

    • Provide multiselection (sap.m.ListBase, property: mode, value: sap.m.ListMode.MultiSelect).
    • Provide an Edit button.
    • If several items are selected, choosing the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

    For details, see mass editing.

    Paste

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

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

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

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

    View Settings

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

    Keep the following in mind:

    • Do not offer any of these features if the grid list is expected to have only a small number of entries (up to 20 in most cases).
    • If filtering is a main use case, do not offer filtering on the toolbar of the grid list. Use the filter bar instead.
    • Always use only the view settings which are really needed. For example, do not offer grouping if it does not support your use case well.
    • Persist the view settings. When a user reopens the app, show the grid list with the same sort, filter, and group settings as last defined by this user.

    Sort

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

    Filter

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

    Group

    • To display the current group state, group headers are shown.
    • On the group header, show the following text (sap.m.GroupHeaderListItem, property: title):
      [Label of the grouped data point]: [Grouping Value]
    • If there is no grouping value, show the following text:
      [Label of the grouped data point]: (Not Available)
      This is the case if you have a group of items that don’t have a value for the grouped data point.

    Enabling/Disabling Actions

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

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

    For more details, see UI Element States.

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

    Message for an action which applies to a part of a selection
    Message for an 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.

    Errors and Warnings

    To indicate that 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.

    To indicate an error in a single item, see States above.

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

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

    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

    Process Flow

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

    Usage

    Use the process flow if:

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

    Do not use the process flow if:

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

    Responsiveness

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

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

    Layout

    The process flow enables different layout forms within the nodes:

    • The default layout contains fixed sections that can easily be filled with content.
    • The freestyle layout comprises an empty container that can be filled with different controls.

    Default (Fixed) Layout

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

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

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

    In turn, each element comprises different sections:

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

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

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

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

    Freestyle Layout

    The freestyle layout gives you the most freedom within the borders of each node. Inside this empty container, you can structure your content as your use case requires. Of course, you still need to conform to the guidelines for each control you use in your layout. The next sections show two examples of freestyle layouts with texts and images.

    If text is the main focus of a node, we recommend using the “dog ear” visualization (property FoldedCorners = true, see Styles section for further details). If an image is the most notable content of a node, we advise against using the “dog ear” visualization.

    Regardless of the controls you use inside the nodes, ensure that users can easily identify the item or meaning behind a node without having to click it. Users should only have to click to retrieve additional information or to perform an action, but not to identify an item. An exception to this rule is the lowest zoom level, which only shows the most basic information.

    What should be displayed at the lowest zoom (level 4) depends on the context and use case of your application. If an image is the centerpiece of the node, a down-sampled version of this image can help users to identify each individual node. In other instances, an icon might be more appropriate to show the status of a node or hint at its content. In both cases, it is mandatory for applications to supply an icon (such as  to indicate that the object is in process, or   to show that the item contains textual information). You can also use status icons with semantic colors if they support the use case.

    You can offer actions on the popover or quick view that is triggered to show additional information. If no additional information is required, you can also use the node’s click event to trigger an action sheet. However, use this latter option with caution; for most use cases, you will need to show additional information, especially at the lowest zoom level.

    Freestyle Example: Text

    If you need to display text inside a node, you can use the built-in click event to show a popover with the full text and any additional actions. While zooming out, less and less text is shown until the smallest zoom level is reached. Since text cannot be previewed in such a small container, use the icon   to indicate that the item contains textual information.

    Layout – Freestyle – Level 1
    Layout – Freestyle – Level 1
    Layout – Freestyle – Level 2
    Layout – Freestyle – Level 2
    Layout – Freestyle – Level 3
    Layout – Freestyle – Level 3
    Layout – Freestyle – Level 4
    Layout – Freestyle – Level 4

    Freestyle Example: Image

    The following examples show how images can be displayed inside the process flow nodes – in this case to represent an employee. Additional information, such as the employee’s profile and contact information, can be shown in a quick view. As the node gets smaller with each zoom level, some information needs to be omitted. On the lowest zoom level, only the image is shown.

    Layout – Freestyle Image - Level 1
    Layout – Freestyle Image - Level 1
    Layout – Freestyle Image - Level 2
    Layout – Freestyle Image - Level 2
    Layout – Freestyle Image - Level 3
    Layout – Freestyle Image - Level 3
    LLayout – Freestyle Image - Level 4
    LLayout – Freestyle Image - Level 4

    Components

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

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

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

    Behavior and Interaction

    Navigation and Zoom

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

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

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

    Level 1

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

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

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

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

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

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

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

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

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

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

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

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

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

    Labels on Connections

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

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

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

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

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

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

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

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

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

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

    Labels - Process flow
    Labels - Process flow

    Highlighted Path

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

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

    Attention: Do not combine a highlighted path with a selected path. When you set one path type, make sure that the other is deactivated.

    Highlight path
    Highlight path

    Business Focus

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

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

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

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

    Business focus
    Business focus

    Editing

    If users can edit a node’s content, offer an Edit button. Place the button on whatever is triggered when the user clicks a node (action sheet, popover, quick view). The editing itself can be handled in a small dialog. The information structure depends on the controls used inside the node. Usually, a form and/or text areas will cover most use cases.

    Styles

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

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

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

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

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

    Aggregation

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

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

    The description on these stacks should be helpful to users, for example, by telling them how many nodes are in the stack. Aggregated amounts can also be shown.
    Use the following format to describe the stack and the number of nodes it contains: <Object Type> (<Counter>). For example, Invoices (8) or Sales Orders (42).

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

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

    Aggregation
    Aggregation
    Aggregation (zoom)
    Aggregation (zoom)

    Guidelines

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

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

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

    UI Texts

    Use a noun to describe the process phase.
    Example: Accounting

    If the process and a business object have the same name, add Processing to the process name.
    Example: Order Processing (in this case, “Order” is used for the business object)

    Resources

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

    Elements and Controls

    Implementation

    Label

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

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

    Label 'Name'
    Label 'Name'

    Usage

    Use the label control if:

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

    Do not use the label control if:

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

    Required/Optional Fields

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

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

    In the image:

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

    Label Placement

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

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

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

    Styles

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

    Wrapping

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

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

    Developer Hint

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

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

    Hyphenation

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

    Guidelines

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

    Exceptions

    The layout can sometimes be simplified by using a placeholder instead of the label control. This exception can be applied in the following cases:

    • In search fields. For more information, see Search.

    Resources

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

    Elements and Controls

    Implementation

    Search

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

    Search field
    Search field

    Usage

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

    Responsiveness

    When suggestions are turned on, the suggestion list displays differently depending on the device type.

    Size S (Smart Phones)

    Clicking the search field opens a new full screen dialog in which items can be selected from a list of suggestions.

    Size S
    Size S

    Size M (Tablets)

    Suggestions are shown below the search field.

    Size M
    Size M

    Size L (Desktops)

    Suggestions are shown below the search field.

    Size L
    Size L

    Types

    SAP Fiori comes with two different search types.

    1. The manual search is triggered explicitly after the user enters text in the search field and clicks the Search button or presses the Enter key.
    2. The live search (also known as “incremental search” or “search-as-you-type”) is triggered by each character that the user enters or deletes. There is a default delay of 400 ms before sending the search data to the back end. This ensures better performance and optimizes user experience. 

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

    Layout

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

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

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

    When the flexible column layout is used to show a list-detail relationship, the search field appears at the top of the list. In full screen mode, the search field is placed at the top of the page.

    Behavior and Interaction

    Entering a Search Term

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

    Deleting a Search Term

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

    Refreshing

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

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

    Search field with 'Refresh' button
    Search field with 'Refresh' button

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

    Pull to Refresh on a touch device

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

    Properties

    The following methods are important.

    For the live search:

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

    For the manual search:

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

    If a Refresh button is needed:

    To show the Search button:

    To ensure the focus is set to input:

    If the search is triggered automatically when the value of the field is changed (unlike the liveChange event, the change event is not fired for each key press):

    • attachChange(oData?, fnFunction, oListener?) Attach event handler fnFunction to the change event of this sap.m.SearchField.
    • detachChange(fnFunction, oListener) Detach event handler fnFunction from the change event of this sap.m.SearchField.
    • fireChange(mArguments?) Fire change event to attached listeners.

    Guidelines

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

    Resources

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

    Elements and Controls

    Implementation

    Message Box

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

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

    Usage

    Use the message box if:

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

    Do not use the message box if:

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

    Responsiveness

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

    Types

    The following categories of messages are available:

    • Error
    • Warning
    • Success
    • Information
    • Confirmation

    Error Message

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

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

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

    Text guidelines for an error message:

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

    Warning Message

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

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

    Use cases for warnings

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

    Warning message with 'OK' button
    Warning message with 'OK' button

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

    Button(s): OK, Cancel

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

    c) Specific decision required, with one action

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

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

    Success Message

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

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

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

    Information Message

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

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

    Button(s): OK

    Information message
    Information message

    Confirmation Message

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

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

    Button(s): Approve, Cancel

    Confirmation message
    Confirmation message

    Confirmation Message with “Note” Section

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

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

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

    Button(s): Approve, Cancel

    Confirmation message with note
    Confirmation message with note

    Confirmation for “Delete”

    If the user clicks Delete, display a “Delete” dialog that confirms the delete action.

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

    Button(s): Delete, Cancel

     

    Use cases for delete confirmation messages in object page and list reports

    a) No context is available. For example, neither the ID nor the description of the business object are available at the time of deletion.
    Body text: Delete this <object>?

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

    b) The ID of the object is available.
    Body text: Delete <object> <object ID>?

    Confirmation for 'Delete' action with object ID
    Confirmation for 'Delete' action with object ID

    c) The object ID and description are both available at the time of deletion.
    Body text: Delete <object> <object ID> “<object description>”?

    Confirmation for 'Delete' action with object ID and description
    Confirmation for 'Delete' action with object ID and description

    Deleting several objects

    If more than one object is being deleted, do not display the object ID and description.
    Body text: Delete the <n = optional> selected <objects>?

    Confirmation for 'Delete' action with several objects
    Confirmation for 'Delete' action with several objects
    Developer Hint
    The default text in SAP Fiori elements will be slightly different, usually using the default term “object” to designate the item to be deleted. When using SAP Fiori elements, replace “object” with the correct business object name. For more information, see Introduction to SAP Fiori Elements – Adjustments.

    Components

    The message box contains the following sections and options:

    Title: Title text appears in the message box header.

    Content: This area contains the actual content of the message box.

    Footer with actions: Although the message box allows more than two buttons, we recommend limiting the number to two. Available button types are primary and negative path actions. If you require other button types, use sap.m.Dialog instead. If no buttons are defined, the default Close button is shown.

    Example of a message box structure
    Example of a message box structure

    Show Details button

    The message displayed for the user should provide sufficient information to ensure that the user knows what has happened. A message box without an explicit details section should be sufficient. Therefore, the Show Details link is only shown if detailed information is available that differs from the message text and is important for the user.

    If details are available, the application has three options to display the text. Text can be displayed as:

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

    Resources

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

    Elements and Controls

    Implementation

    Card

    Information
    Integration cards are already available in SAPUI5, but cannot currently be consumed in the SAP S/4HANA environments (on premise and cloud).

    Intro

    A card represents an app or page. It can be used to launch the app or navigate to the page content. Integration cards are a way of making application content available to end users in a consistent manner.

    Integration cards are similar to the cards on the overview page. However, unlike the overview page cards, integration cards can be used in different host environments.

    A card can show details about a single app or page, or contain related information from multiple sources. An app or page can also be represented by several cards, which each focus on a different aspect of the content.

    Card examples
    Card examples

    When to Use

    You can offer cards on the SAP Fiori launchpad or embed them in other controls.

    Offer a card if:

    • You want to give users easy access to an app or page that is relevant for a business task.
    • You want to show a KPI or a preview of the most important content for the task.
    • You want to let users complete a simple action right away, without navigating to the underlying app.

    Card Anatomy

    A card comprises a header and a content area, which are separated by a divider line. Both components are inside a card container, which includes the background and the border.

    Header

    The header shows what the card is about. There are two variants: the default header and the numeric header.

    Card structure
    Card structure

    Default Header

    The default header shows the basic information about the card and has the following components:

    1. The title is mandatory and represents the “point of view” of the card. Titles longer than three lines are truncated with an ellipsis (…).
    2. Optional: You can use a subtitle to qualify the title or explain the context. Subtitles that exceed two lines are truncated.
    3. Optional: You can use an avatar to provide a visual hint on the card header (for example, an image, icon, or initials).
    4. If the content area contains multiple items, a counter is added to the header. It shows how many items are visible on the card in relation to the total number of relevant items (for example, “6 of 12”).
    Default header
    Default header

    Numeric Header

    Use the numeric header if you need to display numeric information.

    1. Mandatory title
    2. You can add a subtitle with additional qualifying information (optional).
    3. If you specify a currency or unit of measurement, it also appears in the subtitle row. If you provide both a subtitle and a unit of measurement, the display format is: <subtitle text> | <unit of measurement>.
    4. In additional to the general information, you can configure the visualization for a numeric value, such as a KPI.
    5. If required, you can also show up to two additional indicators that relate to the main KPI.
    6. If required, you can display more information about the numeric value directly below it (for example, the period for which a KPI applies).
    Numeric header
    Numeric header
    Guidelines
    Ensure that the card title is short, clear and precise.

    Provide all the information required to interpret the numeric value (specific description, currency or unit of measurement, relevant period).

    • For currencies and standard units of measurement, use the dedicated unitOfMeasurement property. The unit then appears consistently in the subtitle line. If the value is a simple count (such as the number of open tasks), a precise title/subtitle text is usually sufficient.
    • If the value applies to a period, use the footer area (5) to specify the period.

    Content Area

    The content area is reserved for showing information from the underlying source(s). Cards can represent different types of content, with several visualization options. This depends on which card type is used.

    Guidelines
    In the card content area, show the most relevant data for the task at hand.

    Card Types

    The card type defines how content is presented (for example, as a list or table). The embedded controls govern the layout, navigation, and interaction in the card content area.

    The following card types are available:

    List Card

    The list card can display multiple list items of various types.

    Schematic example of a list card
    Schematic example of a list card

    Analytical Card

    The analytical card visualizes analytics data. It can contain a line chart, bar chart, or donut chart.

    Schematic example of an analytical card
    Schematic example of an analytical card

    Table Card

    The table card displays multiple items in a table view.

    Schematic example of a table card
    Schematic example of a table card

    Object Card

    You can use this card type to display information about an object in groups. Each group can contain as many items as needed.

    Schematic example of an object card
    Schematic example of an object card

    Timeline Card

    The timeline card displays time-related content in chronological order.

    Schematic example of a timeline card
    Schematic example of a timeline card

    Calendar Card

    The calendar card shows the schedule for a single entity (typically a person) for a selected day.

    Schematic example of a calendar card
    Schematic example of a calendar card

    Component Card

    The component card allows you to display a SAPUI5 component as content. This gives you significant flexibility in configuring the content.

    Behavior and Interaction

    Card Header

    The whole header is clickable and is the navigation area for opening the underlying source. Clicking the header opens the app or page that relates to the card.

    Card Content

    The content area can have several click areas with different purposes. They depend on the control used and the structure of the content.

    Guidelines
    Always provide meaningful navigation targets. Ensure that the navigation target supports the information flow that starts on the card.
    Card interaction
    Card interaction

    Responsiveness

    The responsive behavior for integration cards depends on the container control of the host environment (for example, SAP Fiori launchpad). The size of the card adapts dynamically to the size of the container.

    Top Tips

    • Cards introduce users to the content in the underlying source. Make sure that your card focuses on the most relevant content.
    • Use cards if supportive visualizations and meaningful navigations are helpful for users.
    • Don’t use individual branding.
    • Avoid unnecessary white space on the card.

    Related Links

    Elements and Controls

    Implementation

    Analytical Table (ALV)

    An analytical table contains a set of data that is structured in rows and columns. It provides several powerful possibilities for working with the data, including advanced grouping and aggregations.

    In contrast to other tables, the analytical data binding used by the analytical table allows an aggregated number to be shown automatically in a cell. This means that a number in such a summarized cell is a total sum of several lines in the database.

    Usage

    Use the analytical table (ALV) if:

    • The cell level and the spatial relationship between cells are more important than the line item. Examples include spreadsheet analyses and waterfall charts. Note that an analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You have to work on more than 1,000 rows. In this case, the analytical table is easier to handle. In contrast to the responsive table, the architecture of the analytical table is optimized for handling large numbers of items. Note that an analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • Comparing items is a major use case. In this case, an analytical table might be more appropriate than a responsive table. In the analytical table, each cell contains only one data point. In contrast, the responsive table is more flexible regarding line items, including the ability to add more data points per cell and also the pop-in function. Both make comparisons more difficult. Note that an analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.

    Do not use the analytical table (ALV) if:

    • You need a table. The responsive table is the default table in SAP Fiori. Additional use cases where you might need the responsive table include:
      • You need to provide a total sum for one column. You can also add totals to the responsive table.
      • The focus is on working on line items, not on cells. The responsive table is optimized for displaying complete items on all devices (such as purchase orders and purchase requisitions).
      • Selecting one or more items is a main use case and details are needed to choose the correct item.
      • Line items are independent of each other and no operation across columns is needed.
      • You want to have only one implementation for all devices.
    • The main use case is choosing one item from a very small number of items with no additional details. A select or combo box might be more appropriate.
    • The main use case is choosing one out of several items with only a few details per item. A list might be more appropriate. Pay attention to the layout of the list item to ensure that it has a pleasant appearance. Examples include the master list and the attachment list.
    • You cannot provide an analytical binding on the technical side. In this case, a grid table will do the work. Note that the grid table provides only one level of grouping, no aggregation options, and is also not responsive.
    • Data needs to be structured in a hierarchical manner. In this case, a tree table might be more appropriate. Although the analytical table can have several grouping levels, it is not as flexible when nodes at several levels contain children. Note that neither the tree table nor the analytical table are responsive. You will need to take an adaptive approach by offering an additional UI for smartphones and tablets.
    • You need an overview of a large amount of data. In this case, use charts.
    • You just need it for layout reasons. In this case, use a layout container like HBox or VBox.
    • You need read-only or editable field-value pairs. Use a form instead. The analytical table is not optimized for form-like input navigation.

    Responsiveness

    The analytical table is available for desktops and tablets, but not in smartphone sizes. It supports touch devices, but is not optimized for small screens.

    If you use an analytical table for desktop use cases, note that you must implement a fallback solution for mobile and touch devices. This fallback solution does not need to support all use cases.

    You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

    Analytical table (ALV) shown on a desktop
    Analytical table (ALV) shown on a desktop
    Analytical table (ALV) shown on a tablet
    Analytical table (ALV) shown on a tablet

    Components

    An analytical table does not consist of other elements. However, it is common to use a toolbar above the analytical table.

    The toolbar can contain entry points for the view settings dialog and the table personalization dialog or for the p13n dialog, as well as for view switches in the form of a segmented button, and buttons for Add, Edit, and other actions.

    Behavior and Interaction

    An analytical table is quite restricted in terms of its content, although it provides powerful features for working with the content.

    Table Level

    Scroll

    An analytical table allows horizontal and vertical scrolling (sap.ui.table.AnalyticalTable, property: navigationMode, value: Scrollbar).

    You can add any number of line items to the analytical table, which is known as “lazy loading”.

    To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.AnalyticalTable, property: rowHeight).

    The analytical table is optimized to allow faster scrolling within the first 1000 items.

    Scroll bar
    Scroll bar

    Select

    Selection for an analytical table depends on the chosen selection mode. The following options are available:

    No selection: Items cannot be selected. (property: selectionMode = None)

    Analytical table without item selection
    Analytical table without item selection

    Single selection: One item in the analytical table can be selected. A row selector column is shown. (property: selectionMode = Single)

    Analytical table with single selection
    Analytical table with single selection
    • Multiple selection: One or more items can be selected. The analytical table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back. The Shift key can be used to select a range. For multiple selection, you can choose between two variants.
      • Multi-toggle mode (property: selectionMode = MultiToggle)
      • Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)

      These variants behave differently when the user selects more items than are currently loaded in the front end.

      Multi-toggle

      In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end (keyboard: Ctrl+A). All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

      Multi-selection plug-in

      If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:

      • By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
      • You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
        • The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and a message can appear (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
        • If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets. (Keyboard: Ctrl+A)
      • If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.
    Information
    When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

    • The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
    • The “minimum limit”: Internally, the analytcial table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.AnalyticalTable, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

    Analytical table with multiple selection
    Analytical table with multiple selection
    Using the multi-selection plug-in with a limit
    Using the multi-selection plug-in with a limit

    Selection Behavior

    An item can be selected in different ways, depending on the configuration of the analytical table (sap.ui.table.Table, property: selectionBehavior):

    • Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection tables if clicking a row or a cell is not used for anything else.
    • RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
    • RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection tables if clicking a row or a cell is not used for another purpose, such as navigation.

    Compact, Cozy, and Condensed

    Like all SAP Fiori controls, the analytical table is shown in compact mode on a desktop and in cozy mode on tablets.

    For desktop devices, you can fit even more rows onto the screen by using the condensed mode together with the compact mode. This renders less white space for each item.

    Note that the condensed content density must always be set in addition to the compact mode. Do not use the condensed mode on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable or unwanted results, such as cozy-sized controls in condensed-sized containers, missing padding, and so on.

    Note that neither compact mode nor condensed mode support touch interaction. Even on a desktop with a touch screen, users will have difficulty selecting rows or using controls inside the cells with their fingers.

    For more information on cozy and compact modes, see content density.

     

     

     

     

    Analytical table in compact mode
    Analytical table in compact mode
    Analytical table in condensed mode - More items on the same screen real estate
    Analytical table in condensed mode - More items on the same screen real estate

    Column Header

    The column header provides the label for the corresponding column and access to the column header menu.

    Columns are resized as follows:

    • Mouse interaction: The user drags the separator line between two columns (sap.ui.table.AnalyticalColumn, property: Resizable). Double-clicking the line optimizes the column according to the length of the data currently visible and the label of the column header (sap.ui.table.AnalyticalColumn, property: Autoresizable).
    • Touch interaction: The user clicks the column header to reveal two buttons: one to show the column header menu and one for resizing. The user drags the latter to resize the column.
    • Keyboard interaction: Users can increase the width of the focused column header with Shift+Right and decrease it with Shift+Left.

    When the user resizes a column, the adaptation of the column width depends on how the column widths are set:

    • If column widths are set in pixel-based units (px, em, rem), the resized column is adapted and subsequent columns are moved accordingly. The width of all other columns is not affected.
      If all the columns together do not use up the full width of the table control, empty space is added. If all the columns together exceed the width of the table control, a scrollbar appears.
    • If all column widths are set as percentages or “auto”, resizing one column automatically resizes one or more other columns. Resizing can also affect the position of the resized column. This option utilizes the full width of the table and ensures that no white space is added. A scrollbar appears only if all or most of the columns become to narrow. To avoid the side effect of undersized columns, you can set a minimum width per column. However, this minimum width is only taken into account if columns are resized automatically. End users can still reduce the column width to below the defined minimum (sap.ui.table.Column, properties: width, minWidth).

    Users can rearrange columns by dragging the column header to another position (sap.ui.table.AnalyticalTable, property: enableColumnReordering). Keyboard interaction: Ctrl+Left and Ctrl+Right move the focused column header one position in the corresponding direction.

    Column header
    Column header
    Opening the column header menu on touch devices
    Opening the column header menu on touch devices
    Columns do not use up the available space
    Columns do not use up the available space

    Column Header Menu

    For each column, a menu can contain the following menu items (sap.ui.table.AnalyticalColumnMenu, property: Visible):

    • Sort Ascending/Descending (sap.ui.table.AnalyticalColumn, property: showSortMenuEntries)
    • Free text filter (sap.ui.table.AnalyticalColumn, property: showFilterMenuEntries)
    • Group
    • Totals
    • Freeze from the first to the last specified column (sap.ui.table.AnalyticalTable, property: enableColumnFreeze)

    For each column, the menu can be replaced by an app-specific menu.

    Column header menu
    Column header menu

    Sort

    The column header menu can provide two sort options (sap.ui.table.AnalyticalColumn, properties: sortProperty, showSortMenuEntry):

    • Sort Ascending
    • Sort Descending

    The user selects one of these options to sort the corresponding column accordingly (sap.ui.table.AnalyticalColumn, properties: sorted, sortOrder, sortProperty).

    Sort settings in column header menu
    Sort settings in column header menu

    Filter

    The column header menu can provide a search field for entering free text (sap.ui.table.AnalyticalColumn, properties: filterProperty, showFilterMenuEntries).

    If the user enters a term in the input field and triggers the search by pressing ENTER when the focus is on the filter input field, the analytical table is filtered by the corresponding column and value (sap.ui.table.AnalyticalTable, properties: filtered, filterProperty, filterValue, filterOperator, sap.ui.table.AnalyticalColumn, property: filterType).

    Note that the filter may return zero results, in which case, the table might be empty.

    General recommendations for filtering:

    • If filtering is a main use case, choose the filter bar or any other filtering UI over the built-in free text filter.
    • Only use the free text filter if filtering is a secondary use case and if the filter bar is too heavy.
    Free text filter in column header menu
    Free text filter in column header menu

    Group

    The column header menu can provide the option to group by this column (sap.ui.table.AnalyticalColumn, property: sortProperty).

    One group collects all items with the same value within the corresponding column.

    Group setting in column header menu
    Group setting in column header menu

    If line items are grouped in a column, every group is provided with a collapsible or expandable group header (sap.ui.table.AnalyticalColumn, property: grouped). The header text consists of the column name and the value for the corresponding group (sap.ui.table.AnalyticalColumn, property: groupHeaderFormatter). Several grouping levels are possible.

    The corresponding column can be hidden to avoid duplicates (sap.ui.table.AnalyticalColumn, property: showIfGrouped). Exercise caution when using this option since hiding the column changes the table layout and may lead to confusion.

    Group headers and the corresponding columns are shown – The relevant data is duplicated
    Group headers and the corresponding columns are shown – The relevant data is duplicated
    Group headers shown, the corresponding column hidden – No duplicates
    Group headers shown, the corresponding column hidden – No duplicates

    Aggregation

    The column header menu can provide the option to show or hide aggregation totals for this column.

    Aggregation in column header menu
    Aggregation in column header menu

    Intermediate aggregations are shown at group level for the corresponding columns if the group contains more than one line item (sap.ui.table.AnalyticalColumn, property: summed).

    Total setting in column header menu
    Total setting in column header menu

    The overall aggregation is shown at the bottom of the analytical table.

    Overall aggregation
    Overall aggregation

    Freeze Columns

    The column header menu can provide the option to freeze columns (sap.ui.table.AnalyticalTable, property: enableColumnFreeze). Selecting Freeze freezes all columns up to the one in which the operation was triggered (sap.ui.table.AnalyticalTable, property: fixedColumnCount).

    When Freeze is triggered, the menu item changes to Unfreeze for the corresponding column.

    Freeze setting in column header menu
    Freeze setting in column header menu

    Line Item Level

    A line item contains a set of cells and provides options for selecting the item.

    To prevent adverse side effects when scrolling vertically, all line items must have the same height.

    (sap.ui.table.AnalyticalTable, property: rowHeight)

    Line item
    Line item

    Drag and Drop

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

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

    Drag and drop is only available on supporting browsers.

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

    Cell Level

    A cell provides one data point.

    It can contain one of the following controls to display this data point:

    While it is technically possible to also use other controls, doing so could lead to issues with alignment, condensed mode, screen reader support, and keyboard support.

    If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false). Do not wrap.

    Cell
    Cell

    Context Menu

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

    When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows (like group headers). Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

    By default, the analytical table provides a context menu on the group headers (for example, Expand, Collapse, …). Otherwise, no default context menus are provided.

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

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

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

    Analytical table with context menu
    Analytical table with context menu

    Guidelines

    Data Density vs. Complexity

    The analytical table can be used to display and work with large amounts of data. Unfortunately, the analytical table has a high data density and therefore conveys an immediate feeling of complexity.

    Only show tables with a lot of data as a last resort. To make the data easier to read, you should instead try the following:

    • Break down the data into manageable chunks and allow the user to navigate or drill down between them.
    • Use charts with drilldown functionality until the amount of data is more manageable.

    Try to avoid horizontal scrolling in the default delivery.

    Try to minimize the number of columns, especially if there is a large number of rows.

    Table Title

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

    Use a table title only if the title of the table is not indicated in the surrounding area.

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

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

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

    If you use a table title, show either a title for the table, with or without variant management, or an item count in the following format:

    Items (2,534).

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

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

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

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

    Selection

    Single Selection

    For single-selection master-detail scenarios within the flexible column layout, do not show an additional “navigated” indicator.

    Multiple Selection

    • We strongly recommend using the multi-selection plug-in. This ensures that all items selected using Select All or as part of a range are included – even if some items were not initially loaded in the front end. This is not the case if you use the multi-toggle option.
    • Do not limit the range selection for the multi-selection plug-in unless you have to.
      • If the dataset is small and/or completely available in the front-end, set the limit property to 0 to enable the Select All option and allow users to select any range.
      • If you have a large dataset, set a limit on the number of selected items to avoid performance issues. Also bear in mind that some actions won’t be helpful if the dataset is too big (for example, a delete operation on 2 million database entries).
    • When setting a limit, also display the corresponding message when the user selects more items at once than the limit allows (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification).
    • In multiple selection mode (multi toggle), do not show checkboxes in the first data column in the default delivery to avoid confusion.
    Don't
    Do not add checkboxes to the first column
    Do not add checkboxes to the first column
    • Never disable the selection checkbox. 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.

    Loading Data

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

    Errors and Warnings

    To indicate that the table contains items with errors or warnings, show a message strip above the table. On the message strip, provide information about errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

    To indicate an error in a single row, see Item States below.

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

    Developer Hint
    The sap.m.plugins.DataStateIndicator displays a message strip above the table, which shows binding-related messages.
    Table containing errors and warnings
    Table containing errors and warnings

    Columns – Best Practices

    Minimize the number of columns. Avoid the need to scroll horizontally in the default delivery.

    By default, the analytical table assigns the same width to each column. We recommend overwriting this default to provide optimal space for your content (sap.ui.table.AnalyticalColumn, property: width).

    If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the size of the browser window results in a scrollbar. If the user resizes a column, and the total width of all columns exceeds the table width, a scrollbar appears. If the columns do not take up the full table width, white space appears to the right of the last column.

    If you define the column width as a percentage, resizing one column affects the width of several or all columns. Reducing the size of the browser window truncates the texts. This ensures that the columns fill up all the available space. A scrollbar appears only if width of all the columns still exceeds the table width after the automatic width adjustments. To avoid the side effect of undersized columns, you can set a minimum width per column. However, this this minimum width is only taken into account if columns are automatically resized. End users can still reduce the column width to below the defined minimum (sap.ui.table.Column, properties: width, minWidth).

    If you set the column width to “auto”, the behavior is the same as for “percentage”. However, unlike “percentage”, “auto” distributes the columns equally.

    To decide on how to set the column width (pixel/rem/em vs. percent/auto), keep the following in mind:

    • For tables with only 2 to 3 columns, use pixel-based units. This ensures that the values in the columns are not spread over the whole screen on wide screens, which improves the readability of the line items.
    • For tables with many columns, where a horizontal scrollbar is usually needed, use pixel based units. This avoids unintended side effects when resizing columns.
    • For all other tables, use whatever fits your case better.

    Be cautious when mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it can also cause even more side effects when resizing a column. If you are using percentage-based widths for one or more columns, consider not allowing end users to resize columns at all.

    Optimize the column width for its initial visible content, including the column header texts. If this is not possible (for example, if showing the full texts would result in extremely wide columns), let the texts truncate. End users can change the width of the column to read the full text, as needed.

    Maintain a constant column width and avoid adjusting it automatically when the content changes.

    Always keep to one line of text. Do not wrap.

    Don't
    Don't truncate the initial visible content In the default delivery
    Don't truncate the initial visible content In the default delivery
    Don't
    Never wrap texts
    Never wrap texts

    Column Headers – Best Practices

    For each column, provide a label in the column header. In the default delivery, do not truncate the column header texts. Only let the text truncate if showing the full text would make the column too wide. Never wrap the text.

    Content Alignment

    For alignment of cell content, follow the guidelines below.

    Left-align: text, IDs, phone numbers, URLs, passwords, and email addresses.

    Left-alignment of text
    Left-alignment of text

    Right-align: numbers, except IDs, to ensure comparability of numbers and amounts.

    Right-alignment of numbers
    Right-alignment of numbers

    Right-align amounts with currencies to the cell and align their respective decimal points.

    This ensures that amounts with different currencies are shown correctly, regardless of whether the currencies have 0, 2, or 3 decimals.

    For aligning to the decimal point, use the sap.ui.uinified.Currency control.

    Alignment to the decimal point
    Alignment to the decimal point

    Right-align dates and times.

    This ensures comparability for most formats and locales.

    Right-alignment of dates
    Right-alignment of dates

    Left-align status information.

    Left-align status information
    Left-align status information

    Center-align icons.

    Left-align micro charts.

    XS micro charts in condensed mode
    XS micro charts in condensed mode

    Content Formatting

    Key Identifier

    Use a bold label or an emphasized link as the key identifier of an item. In the default delivery, show the key identifier in the first column.

    Emphasized link
    Emphasized link

    For strings with IDs, use one of the following:

    • Show the ID in a separate column. Use this format if users need to sort, group, or filter by both the string and the ID.
    • Show the ID in parentheses after the corresponding string. In this case, you must opt for one criterion for sorting, filtering, and grouping – either the string or the ID. This option is then used for all sort, filter and group actions and can’t be changed later by the user. Use this format only if users don’t need to sort, filter, and group by both the string and the ID.
    Text and ID in two columns – Allows sorting, filtering, and grouping for both
    Text and ID in two columns – Allows sorting, filtering, and grouping for both
    If displayed as a link, use only the string as the link, not the ID
    If displayed as a link, use only the string as the link, not the ID
    Text and ID in one column – Sorting, filtering, and grouping are available for either the text or the ID, but not for both
    Text and ID in one column – Sorting, filtering, and grouping are available for either the text or the ID, but not for both
    If displayed as a link, use the whole text as the link
    If displayed as a link, use the whole text as the link

    Truncation

    Avoid truncation of typical content in the default delivery (sap.ui.table.AnalyticalColumn, property: width). However, since the columns are resizable, do not worry too much if truncation occurs as columns can still be enlarged if necessary.

    To prevent adverse side effects when scrolling vertically, all line items must also have the same height. If you need to decide between truncation and different row heights, choose truncation. Do not wrap.

    Optimize column width for typical content, not all content
    Optimize column width for typical content, not all content

    Number of Links

    Are there too many links? Use subtle links to avoid a wall of links. Standard links are also emphasized more if they are surrounded by subtle links.

    For example, a financial table consists of several columns with summarized cells. A summarized cell shows the total sum of several database entries. Each sum should be a link to a report that shows details about which database entries produce the total sum. The line item identifier should also be a link that provides more detail about the line item itself. Use a standard or emphasized link for the item identifier, and subtle links for the summarized cells.

    Emphasized links, links, subtle links, and text
    Emphasized links, links, subtle links, and text

    Missing Value

    If there is no value for a cell, leave it blank. Do not display text as N/A.

    Leave empty fields blank
    Leave empty fields blank

    Numbering Items

    In terms of numbering items:

    • If the item number is more like an ID with regard to its description, use ID formatting as described above.
    • In all other cases, use a separate column for the item number.
    Add a separate column for the item number
    Add a separate column for the item number

    Status

    For status information, use semantic colors on the foreground elements.

    For status information on text, use an object status.

    Semantic colors on text
    Semantic colors on text

    Micro Charts

    Use only the following micro charts: Bullet, comparison, stacked bar. When using micro charts, use them in size XS.

    Micro charts in an analytical table
    Micro charts in an analytical table

    Empty Tables

    Avoid empty analytical tables. If necessary, provide instructions on how to fill the analytical table with data (sap.ui.table.AnalyticalTable, properties: noDataText, showNoData).

    Examples:

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

    Adapt the texts above if:

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

    Invalid State

    To show an invalid state of the analytical table within the list report floorplan, show an overlay on the analytical table and the corresponding toolbar (sap.ui.table.AnalyticalTable, property: showOverlay). The overlay prevents user interactions.

    Use this within the list report floorplan if filter settings have been changed but the analytical table has not yet been updated.

    Analytical table with invalid data
    Analytical table with invalid data

    Item States

    To show that an item has been modified, for example, within the global edit flow, add the string (Modified) in an additional column with the label Editing Status.

    In the default delivery, add a column directly behind the key identifier.

    A modified item
    A modified item

    To show that a modified item contains an error, for example, within the global edit flow, add the string Contains errors in the Editing Status column and highlight the row accordingly. This string replaces the Modified string.

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

    To show that an item is locked, add a transparent-style button with the corresponding icon and the text Locked by [name] in the Editing Status column.

    A locked item
    A locked item

    To show that an item is in draft state, add a transparent-style button with the text Draft in the Editing Status column.

    Item in draft state
    Item in draft state

    Show only one state at a time.

    Numbers and Units

    Show the unit of measurement in one of the following ways:

    The number and unit are in the same cell. Do this if sorting, filtering, or grouping by the unit of measurement are not needed.

    For amounts, use a currency control to display the concatenated string.

    Number and unit of measurement in one cell
    Number and unit of measurement in one cell

    The number and unit are in separate columns. Do this if sorting, filtering, or grouping by the unit of measurement are a common use case.

    Note that this column can be hidden or moved independently of the column containing the corresponding number. Therefore, be sure to have clear labels for both columns to communicate the dependency.

    Number and unit of measurement in two columns
    Number and unit of measurement in two columns

    If the unit of measurement is the same for all rows, show the unit of measurement in the column header. Otherwise, show the unit of measurement within the row.

    Drag and Drop

    Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, 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. These are keyboard operable and available on all browsers.

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

    Do not use drag and drop for rearranging items in the analytical table. The analytical table is mainly used for grouping items and for calculating the totals per group and column. Moving items to another group also means that a value of the dropped item changes: because grouping is based on values in a column, the dropped item needs to take on the value of the target group for the corresponding column.

    Example:
    A table is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. Because changing the value in this way doesn’t make sense, rearranging items is not permitted in analytical tables.

    Don't
    Do not use drag and drop for rearranging items in the analytical table
    Do not use drag and drop for rearranging items in the analytical table

    Context Menu

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

    The context menu can be triggered for the table, row, or cell. However, we do not recommend using context menus for cells: because the content of a cell is a different touch target than the cell itself, opening a cell context menu via touch is quite hard, even in cozy mode.

    Do not combine context menus with condensed mode: editable controls fill the entire space inside a cell. Because of this, context menus cannot be opened at all with touch or mouse interaction.

    Actions

    Multiple Items

    To trigger actions on multiple items, use a multiselection analytical table (sap.ui.table.AnalyticalTable, property: selectionMode, value: MultiToggle). Offer the corresponding actions in the table toolbar.

    Do not offer action triggering on multiple items if the table is generally expected to have fewer than 10 items. In this case, try to use the responsive table instead of the analytical table.

    Single Item

    To trigger actions on a single item (sap.ui.table.AnalyticalTable, property: selectionMode, value: Single):

    • Show the actions on the table toolbar.
    • In rare cases, show the actions within the line item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. Provide a separate column per action. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

    Single Cell

    To trigger actions on a single cell, create the corresponding click event. Do not use the cell click event if the cell contains interactive controls, such as links.

    To trigger navigation on line item level choose one of the following options:

    • Use a link for the attribute that identifies the row. Clicking the link triggers the navigation.
    • Add the RowActions column and show the navigation indicator (  ) at the end of the row. The navigation arrow triggers the navigation.

    Special case: Multi-selection in a master-detail scenario
    When a multi-selection table is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case, you can display a “navigated” indicator to show which item is currently open.

    Use the RowActions column only for one or both of the following actions:

    • Navigate to details page ( )
    • Delete ( )

    The RowActions column does not provide a column header text. It is fixed and will not scroll away. Users also cannot personalize this column.

    Navigate to details page
    Navigate to details page

    Single Cell

    For triggering actions on a single cell, create the corresponding click event. Do not use the cell click event if the cell contains interactive controls, such as links.

    Add Items

    To let users add items, place an Add or Create text button on the table toolbar.

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

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

    Enable the shortcut Ctrl+Enter (and ideally also Enter) to trigger the Add or Create button.

    There are three options for adding an item. 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. Only use this option 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.

    Depending on the flow, an item can be in one of three different states:

    • New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
    • Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item in the table. Ignore current sort, filter and grouping criteria to keep the item visible.
    • Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is applied as follows:
      • Inline creation: After Save is triggered on the table toolbar or at page level.
      • Create with dialog: A table showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

    If draft handling is used, new items are not saved at table level, but rather with the entire draft.

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

    Enabling/Disabling Actions

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

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

    For more details, see UI Element States.

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

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

    Editable Content

    For editable content, only use the following controls, and only one control per cell:

    Only these controls are optimized for all viewing modes of the analytical table.

    If you need edit mode, change your text controls, such as label, text, link, object status, icons, and currencies, to editable controls as soon as you switch to edit mode, but not before. You can do this by exchanging the controls, for example, from sap.m.Text to sap.m.Input.

    For mass editing items:

    • Provide multiselection.
    • Provide an Edit button.
    • If several items are selected, clicking the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

    This is similar to mass editing in the split-screen layout floorplan.

    Warning
    Do not offer editing for summarized cells. A summarized cell shows the total sum of several database entries. Changing the total sum does not make sense since it is unclear how this sum is divided between the different database entries.
    Interactive controls – Inline
    Interactive controls – Inline

    View Settings

    There are several ways to show Sort, Filter, and/or Group settings:

    • Column header menu: In all cases, show the corresponding settings in the column header menu.
    • View settings dialog: Simple and more flexible with regard to filter settings. No advantage for sorting. Allows the user to ungroup grouped columns.tables with a medium amount of items.
    • Table personalization dialog: Provides complex options for sorting items by several levels and allows the user to ungroup grouped columns. It also provides a query-builder-like approach for filter settings. The complexity of the options is also its downside. Use the table personalization dialog for tables with a large number of items.
    • If filtering is a main use case, use the filter bar. In this case, avoid offering additional filter settings on the table. If you do, the filter settings on the table work only on the result set provided by the filter bar.

    Always be careful when synchronizing the settings in the dialog with the settings from the column header menu.

    Trigger the dialogs in one of the following ways:

    • View settings dialog: Provide several buttons, one for each of these view settings. Each button opens the view settings dialog on the corresponding page.
    • Table personalization dialog: Provide a settings button, which opens the table personalization dialog containing all pages.

    Use only the view settings you really need. For example, do not offer grouping if it does not support your use case.

     

    Column header menu with view settings
    Column header menu with view settings
    Table toolbar with triggers for view settings dialog
    Table toolbar with triggers for view settings dialog
    Table toolbar with trigger for table personalization dialog
    Table toolbar with trigger for table personalization dialog

    Persist the view settings. When a user reopens the app, show the analytical table with the same sort, filter, group, and aggregation settings as last defined by this user.

    Sort

    Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the first column in the default delivery.

    To display the current sort state, an icon is shown in the column header of the last sorted column. This icon indicates the sort direction (sap.ui.table.AnalyticalColumn, properties: sorted, sortOrder, sortProperty).

    For the default sort setting, sort by the column that identifies the row, which is usually the first column in default delivery. Use a meaningful sort order, such as alphabetical order for text, numeric order for numbers, or chronological order for dates.

    Column, sorted ascending
    Column, sorted ascending
    Column, sorted descending
    Column, sorted descending

    The descending sort order must always be the exact reverse of the ascending sort order.

    For each column, provide a meaningful sort order. For example:

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

    Filter

    To display the current filter state, an icon is shown in the column header of the filtered column (sap.ui.table.AnalyticalColumn, properties: filtered, filterProperty, filterValue, filterOperator, defaultFilterOperator, filterType).

    Column, filtered
    Column, filtered

    Group

    To display the current group state, group headers are shown. Show the following text in the group header (sap.ui.table.AnalyticalColumn, properties: grouped, showIfGrouped, groupHeaderFormatter):

    [Label of the grouped column]: [Grouping value]

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

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

     

    Set the property collapseRecursive to “false” to keep subgroups expanded even after collapsing and expanding the parent group.

    Group headers, several levels
    Group headers, several levels

    On non-touch devices, right-clicking a group header opens the group header menu. On touch devices, the same menu is opened by using the menu icon on the right side of a group header.

    The group header menu provides several options:

    • Show/Hide: Shows or hides the column in the table layout, although it is grouped.
    • Ungroup: When the user ungroups a column, the corresponding group headers disappear. If the column was hidden, it is shown again as a separate column.
    • Ungroup All: The columns are shown again.
    • Move Up: Rearranges the grouping levels hierarchy by moving the selected group above the group that is one level higher up in the hierarchy.
    • Move Down: Rearranges the grouping levels hierarchy by moving the selected group below the group that is one level lower down in the hierarchy.
    • Collapse Level: Collapses all groups on the corresponding grouping level.
    • Collapse All: All groups are collapsed.
    Group header menu
    Group header menu
    Group header on touch devices
    Group header on touch devices

    In general:

    • Offer grouping on objects and attributes.
    • Do not offer grouping on measures.
    • If appropriate, offer reasonable grouping by default, but do not exaggerate. As a rule of thumb, use up to three group levels.
    • Provide more space for the first column. Grouping needs an indent per group level. Extra space in the first column prevents truncated text.

    Aggregate

    To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.

    If items are grouped, an intermediate sum is shown:

    • At the bottom of each group if the group is expanded.
    • In the group header if the group is collapsed.

    (sap.ui.table.AnalyticalColumn, property: summed)

    When aggregating amounts with different units of measurement, show an asterisk (*) in the aggregation rows.

    When sorting an aggregated column, only the leaf nodes of a group are included by default. If each measure column currently displays a single unit of measurement, the order of the groups can also be affected.

    For example:
    Let’s assume that table items are grouped by Country/Region and aggregated by Total Net Amount. If you sort the Total Net Amount column in descending order, the largest total net amount is shown first.

    Warning
    Only enable sorting by totals if each column has a single unit of measurement. This prevents inconsistencies in the sorting behavior, which depends on user settings, such as filter settings or the columns currently displayed.
    Developer Hint
    To allow sorting by totals, the following conditions must be met:

    1. For each measure column, multiple units must not occur in the displayed data, regardless of whether or not totals are shown.
    2. The autoExpandMode of the AnalyticalBinding must be set to Sequential. Note that the default is Bundled.

    In general:

    • Offer aggregation on measures, but not on objects or attributes.
    • Avoid aggregations on the first three columns for the default delivery. As soon as grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.
    • Where appropriate, offer reasonable aggregation by default.
    Aggregation and groups
    Aggregation and groups

    Personalization

    Only offer personalization if you need more columns than a tablet screen can display at any one time, which is usually five.

    Persist the column layout. When a user reopens the app, show the analytical table with the same column layout settings as last defined by this user.

    Add, Remove, and Rearrange Columns

    To add, remove, or rearrange columns, use one of the following:

    • The table personalization dialog: It offers some simple settings for column layout. Use this if you have only a few columns to choose from and/or you use the view settings dialog.
    • The p13n dialog: Besides various complex view settings, it also provides settings for column layout. Use this if you have a large number of columns to choose from and/or you use this dialog anyway for view settings.

    In both cases, trigger the dialog via the settings button in the table toolbar. As short cut, use CTRL+COMMA.

    You can also use drag and drop to rearrange columns (sap.ui.table.Table, property: enableColumnReordering). If you allow rearranging via drag and drop as well as via a dialog, keep both places in sync.

    Resize Columns

    Resizing columns works differently on touch and non-touch devices.

    • Non-touch devices: Drag and drop the column separator on the right side of the column. Double-clicking the column separator optimizes the width of the column for the data currently loaded into the front end, which is usually about 100 rows.
    • Touch devices: Clicking the column header reveals two buttons: one for opening the column header menu, another one for resizing the column. Drag and drop this second button to resize the column.

    Freeze Columns

    For freezing columns, offer the setting in the column header menu (sap.ui.table.AnalyticalTable, property: enableColumnFreeze).

    Selecting Freeze on a column freezes all columns from the first one to the one where Freeze is selected. On this column, the menu entry changes from Freeze to Unfreeze.

    Frozen column
    Frozen column

    Highlight Items

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

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

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

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

    (sap.ui.table.AnalyticalTable, aggregation: rowSettingsTemplate)

    Highlighted items
    Highlighted items

    Tables in Object Pages

    In the object page, we advise against using analytical, grid, and tree tables. Instead, use a responsive table and offer navigation to a list report with the table types mentioned above.

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

    Export to Spreadsheet

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

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

    Properties

    sap.ui.table.AnalyticalTable

    The following additional properties are available for the analytical table:

    • The property: width defines the width of the analytical table.
    • The property: rowHeight defines the height of each row in the analytical table. Since the height required is calculated automatically by the analytical table, this property is only needed rarely.
    • The property: columnHeaderHeight defines the height of the column headers. Since the height required is calculated automatically by the analytical table, this property is only needed rarely.
    • The property: columnHeaderVisible can be used to hide the column headers. Always show the column headers.
    • The property: showColumnVisibilityMenu provides an additional entry in the column header menu that allows columns to be shown or hidden. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
    • The property: columnVisibilityMenuSorter is used for sorting the columns inside the column header menu if showing and hiding columns is provided in the menu. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
    • The property: visibleRowCount defines the height of the analytical table. Show as many rows as fit on the screen.
    • The property: visibleRowCountMode defines whether the height of the analytical table is fixed or automatically calculated based on the space provided by the underlying container. For automatic calculation, make sure that all rows have the same height.
    • The property: minimumAutoRowCount defines the minimum number of rows that must be shown if the property: visibleRowCountMode is set to “auto”. Show at least three to five rows.
    • The property: firstVisibleRow defines the first row shown in the visible area of the analytical table. The analytical table is scrolled accordingly.
    • The property: allowColumnReordering is deprecated. Use the property: enableColumnReordering instead.
    • The property: editable does not have a visible effect. Please do not use it.
    • The property: threshold is used for optimizing lazy loading of items. In most cases, the default value is appropriate.
    • The property: enableGrouping is experimental and does not have a meaningful effect on the analytical table. Do not use it.
    • The property: sumOnTop shows additional aggregation values on the group header, even if the group is expanded. Do not use it.
    • The property: enableCustomFilter changes the filter entry in the column header menu from an edit box to Filter…. Selecting this entry throws an event that apps can react to, for example, by opening a dialog. In general, you should choose the built-in filter over your own implementation. Specifically, keep filtering via the column header menu simple, while offering more advanced options via the table personalization dialog.
    • The property: enableBusyIndicator has not yet been fully implemented. Do not use it.
    • The property: title adds a line of text on top of the analytical table. Do not use it. To add a title to the table, use a toolbar.
    • The property: footer adds a short text at the bottom of the table.
    • The property: Busy sets the analytical table to busy state. While in busy state, the whole table cannot be used and items cannot be read due to an overlay.
    • The property: Tooltip does not have an effect. Do not use it.
    • The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). Do not use it.

    sap.ui.table.AnalyticalColumn

    The following additional properties are available for the analytical column:

    • The property: leadingProperty is used for data binding.
    • The property: inResult is used for data binding.
    • The property: visible defines whether a column is shown or hidden.
    • The property: name defines the name shown in the column header menu for showing and hiding columns. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Please do not use this property.
    • The property: headerSpan defines whether one column header is used for one or several columns. To prevent adverse side effects, always use one column header for only one single column. Please do not use this property.
    • The property: Tooltip does not have an effect. Please do not use it.

    Resources

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

    Elements and Controls

    Implementation

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

    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.

    Items can be navigated in all directions using the Arrow keys. To skip several rows, Page Up and  Page Down can be used. To move the focus to the first / last item use the Home and End keys.

    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. Users can (de)select all items using Ctrl+A. Select All must (de)select all items that the user can reach by scrolling. Try to avoid combining multi selection with navigation.
    An unselected and a selected item in
    An unselected and a selected item in "multi selection"
    Guidelines

    • Never disable the selection checkbox. 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.
    • 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.
    • For single-selection master-detail scenarios within the flexible column layout, use the mode “single select master”. Do not show an additional “navigated” indicator.
    • Avoid the mode “single select left”. It removes the possibility of clicking somewhere on the item to select it. Use it only if it is really necessary to have two different click areas; a small one for a selection, and the rest of the item for something else.
    • If selecting / deselecting all items is important for your app, add a button Select All to the toolbar. Change the button text to Deselect All if all items are selected.

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

    Loading Data

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

    Empty Grid Lists

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

    Examples:

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

    Adapt the texts above if:

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

    Context Menu

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

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

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

    Group

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

    A grouped grid list
    A grouped grid list

    Guidelines

    Actions

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

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

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

    To trigger actions on a single item only (sap.m.GridList, property: mode, value: sap.m.ListMode.SingleSelectMaster), the action can also be shown within the item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every item and thus use a lot of screen real estate, only do this for one or two actions at most. In this case, show the action trigger near the content to which it belongs. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

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

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

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

    Design for Performance

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

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

    The actual limits depend on your concrete scenario, including:

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

    Add Items

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

    Depending on the flow, an item can be in one of three different states:

    • New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
    • Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the grid list. Ignore current sort, filter, and grouping criteria to keep the item visible.
    • Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
      • Inline creation: After Save was triggered on the toolbar or at page level.
      • Create with dialog: A grid list showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

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

    Export to Spreadsheet

    Mass Editing

    • Provide multiselection (sap.m.ListBase, property: mode, value: sap.m.ListMode.MultiSelect).
    • Provide an Edit button.
    • If several items are selected, choosing the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

    For details, see mass editing.

    Paste

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

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

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

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

    View Settings

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

    Keep the following in mind:

    • Do not offer any of these features if the grid list is expected to have only a small number of entries (up to 20 in most cases).
    • If filtering is a main use case, do not offer filtering on the toolbar of the grid list. Use the filter bar instead.
    • Always use only the view settings which are really needed. For example, do not offer grouping if it does not support your use case well.
    • Persist the view settings. When a user reopens the app, show the grid list with the same sort, filter, and group settings as last defined by this user.

    Sort

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

    Filter

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

    Group

    • To display the current group state, group headers are shown.
    • On the group header, show the following text (sap.m.GroupHeaderListItem, property: title):
      [Label of the grouped data point]: [Grouping Value]
    • If there is no grouping value, show the following text:
      [Label of the grouped data point]: (Not Available)
      This is the case if you have a group of items that don’t have a value for the grouped data point.

    Enabling/Disabling Actions

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

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

    For more details, see UI Element States.

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

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

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

    To trigger a default action on the whole item, use the “Active” or “DetailAndActive” list item type (sap.f.GridListItem, property: type, value: sap.m.ListType.Active).
    Active items trigger an event when clicked, which can be handled by apps (for example, to open a dialog). Clicks on interactive controls within the item do not trigger the event but are handled by the interactive control. Do not use Active for navigation, to switch the line item to an edit state, or to delete the item.

    Active can be combined with edit and delete, but not with navigation. Do not combine active with single selection.

    Errors and Warnings

    To indicate that 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.

    To indicate an error in a single item, see States above.

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

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

    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

    Grid Table

    A grid table contains a set of data that is structured in rows and columns. It allows the user to scroll in both directions and can handle large numbers of items and columns.

    Usage

    Use the grid table if:

    • The cell level and the spatial relationship between cells are more important than the line item. Examples include spreadsheet analyses and waterfall charts. Note that a grid table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You have to work on more than 1,000 rows. In this case, the grid table is easier to handle. In contrast to the responsive table, the architecture of the grid table is optimized for handling large numbers of items. Note that a grid table is not fully responsive. It is only available for desktop and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • Comparing items is a major use case. In this case, a grid table might be more appropriate than a responsive table. In the grid table, each cell contains only one data point. In contrast, the responsive table is more flexible regarding line items, including the ability to add more data points per cell and also the pop-in function. Both make comparisons more difficult. Note that a grid table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You need an analytical table, but you cannot provide an analytical binding on the technical side. In this case, a grid table will do the work. Note that the grid table provides only one level of grouping, no aggregation options, and is also not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.

    Do not use the grid table if:

    • You need a table. The responsive table is the default table in SAP Fiori. Additional use cases where you might need the responsive table include:
      • The focus is on working on line items, not on cells. The responsive table is optimized for displaying complete items on all devices, such as file browsing and a list of documents you want to act on, like purchase orders and purchase requisitions.
      • Selecting one or several items is the main use case and details are needed to choose the correct item.
      • Line items are independent of each other and no operation across columns is needed.
      • You want to have only one implementation for all devices.
    • The main use case is choosing one item from a very small number of items with no additional details. A select or combo box might be more appropriate.
    • The main use case is choosing one out of several items with only a few details per item. A list might be more appropriate. Pay attention to the layout of the list item to ensure that it has a pleasant appearance.
    • Data needs to be structured in a hierarchical manner. Use a tree table instead. Note that neither the tree table nor the grid table are responsive. You will need to take an adaptive approach by offering an additional UI for smartphones and tablets.
    • You need an overview of a large amount of data. In this case, use charts.
    • You just need it for layout reasons. In this case, use a layout container such as HBox or VBox.
    • You need read-only or editable field-value pairs. Use a form instead. The grid table is not optimized for form-like input navigation.

    Responsiveness

    A grid table is available for desktops and tablets, but not in smartphone sizes. It supports touch devices, but is not optimized for small screens.

    If you use a grid table, note that you have to implement a fallback solution for small screens. This fallback solution does not need to support all use cases.

    You could create a fallback by using a responsive table, but a completely different solution, such as showing charts in a read-only case, might be more appropriate.

    Grid table shown on a desktop
    Grid table shown on a desktop
    Grid table shown on a tablet
    Grid table shown on a tablet

    Layout

    1. Select All – The Select All checkbox selects or deselects all items.
    2. Column header – The column header allows the user to resize and rearrange columns. It also provides access to a menu with column-specific commands.
    3. Selector cells – The selector cells allow the user to select one or more items.
    4. Items – The collection of items, or rows, occupies the main part of the grid table.
    Schematic visualization of the grid table
    Schematic visualization of the grid table

    Components

    A grid table does not consist of other elements. However, it is common to use a toolbar above the grid table.

    The toolbar can contain entry points for the view settings dialog and the table personalization dialog or for the p13n dialog, as well as view switches in the form of a segmented button, and buttons for Add, Edit, and other actions.

    Behavior and Interaction

    A grid table is quite restricted in terms of its content.

    Table Level

    Scroll

    A grid table allows horizontal and vertical scrolling (sap.ui.table.Table, property: navigationMode, value: Scrollbar).

    You can add any number of line items to the grid table, which uses “lazy loading”.

    To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.Table, property: rowHeight).

    The grid table is optimized to allow faster scrolling within the first 1000 items.

    Scrollbar
    Scrollbar

    Select

    Selection Mode

    Selection for a grid table depends on the chosen selection mode. The following options are available:

    No selection: Items cannot be selected. (property: selectionMode = None)

    A non-selection grid table
    A non-selection grid table

    Single selection: One item in the grid table can be selected. A row selector column is shown. (property: selectionMode = Single)

    A single-selection grid table
    A single-selection grid table

    Multiple selection: One or more items can be selected. The grid table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back. The Shift key can be used to select a range.

    For multiple selection, you can choose between two variants.

    • Multi-toggle mode (property: selectionMode = MultiToggle)
    • Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)

    These variants behave differently when the user selects more items than are currently loaded in the front end.

    Multi-toggle

    In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end (keyboard: CTRL+A). All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

    Multi-selection plug-in

    If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:

    • By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
    • You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
      • The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and you can display a corresponding message (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
      • If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets. (Keyboard: CTRL+A)
    • If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.
    Information
    When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

    • The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
    • The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.Table, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

    A multiselection grid table
    A multiselection grid table
    Using the multi-selection plug-in with a limit
    Using the multi-selection plug-in with a limit

    Selection Behavior

    An item can be selected in different ways, depending on the configuration of the grid table (sap.ui.table.Table, property: selectionBehavior):

    • Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection grid tables if clicking a row or a cell is not used for anything else.
    • RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
    • RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection grid tables if clicking a row or a cell is not used for another purpose, such as navigation.

    Compact, Cozy, and Condensed

    Like all SAP Fiori controls, the grid table is shown in compact mode on a desktop and in cozy mode on tablets.

    For a desktop, you can also display even more rows on the same screen height by adding the condensed mode in addition to the compact mode. This renders less white space for each item.

    Note that the condensed content density has always to be set in addition to compact. Do not use condensed on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable and / or unwanted results, e.g. cozy sized controls in condensed sized containers, missing padings, etc.

    Note that neither compact mode nor condensed mode can be interacted with via touch. Even on a desktop with a touch screen, users will have difficulty selecting rows or using controls inside the cells when using their fingers.

    Furthermore, condensed mode is not available for Internet Explorer 9. If condensed mode is to be used, please provide a fallback.

    For more information on cozy and compact modes, see content density.

    Column Header

    The column header provides the label for the corresponding column and access to the column header menu.

    Columns are resized as follows:

    • Mouse interaction: The user drags the separator line between two columns (sap.ui.table.Column, property: Resizable). Double-clicking the line optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable).
    • Touch interaction: The user taps the column header to reveal two buttons – one to show the column header menu, and one for resizing. The user drags the latter to resize the column.
    • Keyboard interaction: The width of the focused column header can be increased via Shift+Right and decreased via Shift+Left.

    After resizing a column, the adaptation of the column widths depends on how the column width is set:

    • If column widths are set in pixel-based units (px, em, rem), the corresponding column is adapted and the columns that follow are moved accordingly. The width of all other columns is not affected.
      If all the columns together take up less width than the table control, an empty space is added. In case all columns together take up more width than the table control, a scrollbar appears. (sap.ui.table.Column, property: width)
    • If all column widths are set in percentage or “auto”, resizing one column might also lead to the automatic resizing of some or all other columns. The position of the resized column might also be affected. This is done to ensure that the whole table width is used and no white space is added. A scrollbar appears only if all or most of the columns shrink significantly. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

    Columns can be rearranged by dragging the column header to another position (sap.ui.table.Table, property: enableColumnReordering). Keyboard: the focused column header can be moved by one position in the corresponding direction via Ctrl+Left / Ctrl+Right.

    Column header
    Column header
    Opening the column header menu on touch devices
    Opening the column header menu on touch devices
    Fewer columns than space available
    Fewer columns than space available

    Column Header Menu

    For each column, a menu can contain the following menu items (sap.ui.table.ColumnMenu, property: visible):

    • Sort Ascending/Descending (sap.ui.table.Column, property: showSortMenuEntries)
    • Free text filter (sap.ui.table.Column, property: showFilterMenuEntries)
    • Group (sap.ui.table.Table, property: enableGrouping)
    • Freeze from the first to the last specified column (sap.ui.table.Table, property: enableColumnFreeze)

    For each column, the menu can be replaced by an app-specific menu.

    Column header menu
    Column header menu

    Sort

    The column header menu can provide two sort options (sap.ui.table. Column, properties: sortProperty, showSortMenuEntry):

    • Sort Ascending
    • Sort Descending

    The user selects one of these options to sort the corresponding column accordingly (sap.ui.table. Column, properties: sorted, sortOrder, sortProperty).

    Sort settings in column header menu
    Sort settings in column header menu

    Filter

    The column header menu can provide a search field for entering free text (sap.ui.table.Column, properties: filterProperty, showFilterMenuEntries).

    If the user enters a term in the input field and triggers the search by pressing Enter when the focus is on the filter input field, the grid table is filtered by the corresponding column and value (sap.ui.table.Table, properties: filtered, filterProperty, filterValue, filterOperator, sap.ui.table.Column, property: filterType).

    Note that the filter may return zero results, in which case, the table might be empty.

    General recommendations for filtering:

    • If filtering is a main use case, choose the filter bar or any other filtering UI over the built-in free text filter.
    • Only use the free text filter if filtering is a secondary use case and if the filter bar is too heavy.
    Free text filter in column header menu
    Free text filter in column header menu

    Group

    The column header menu can provide the option to group by this column (sap.ui.table.Column, property: enableGrouping).

    A group collects all items with the same value within the corresponding column.

    Group setting in column header menu
    Group setting in column header menu

    If line items are grouped in a column, every group is provided with a collapsible or expandable group header. The header text consists of the name of the value and the number of items in the specific group. Only one grouping level is possible.

    Group header
    Group header

    Once line items have been grouped, the corresponding column is hidden. There is no built-in option to ungroup the grid table again. Therefore, provide a view settings dialog or table presonalization dialog to offer an additional way to group by a column and a way to ungroup the complete table.

    An exception to this is when the table is grouped from the start and should not be ungrouped at all.

    Group headers shown, the corresponding column hidden: no duplicates, but a confusing change
    Group headers shown, the corresponding column hidden: no duplicates, but a confusing change
    Warning
    Note that grouping the grid table is experimental and currently works only on items loaded to the front end. Thus, scrolling down the table leads to data not being grouped as expected.

    Only use this feature if you have just a few line items, all of which are loaded to the front end. If this is the case, consider using a responsive table instead of a grid table.

    Freeze Columns

    The column header menu can provide the option to freeze columns (sap.ui.table.Table, property: enableColumnFreeze). Selecting Freeze freezes all columns up to the one in which the operation was triggered (sap.ui.table. Table, property: fixedColumnCount).

    When Freeze is triggered, the menu item changes to Unfreeze for the corresponding column.

    Freeze setting in column header menu
    Freeze setting in column header menu

    Line Item Level

    A line item contains a set of cells and provides options for selecting the item.

    To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.Table, property: rowHeight).

    Line item
    Line item

    Drag and Drop

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

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

    Drag and drop is only available on supporting browsers.

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

    Context Menu

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

    When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows (like group headers). Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

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

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

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

    Grid table with a context menu
    Grid table with a context menu

    Cell Level

    A cell provides one data point.

    It can contain one of the following controls to display this data point:

    While it is technically possible to also use other controls, doing so could lead to issues in regards to alignment, condensed mode, screen reader support, and keyboard support.

    If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false). Do not wrap.

    Cell
    Cell

    Guidelines

    Data Density vs. Complexity

    The grid table can be used to display large amounts of data. Unfortunately, the grid table has a high data density and therefore conveys an immediate feeling of complexity.

    Only show tables with a lot of data as a last resort. Try the following instead:

    • Break down the data into manageable chunks and allow the user to navigate or drill down between them.
    • Use charts with drilldown functionality until the amount of data is more manageable.

    Try to avoid horizontal scrolling in the default delivery.

    Try to minimize the number of columns, especially if there is a large number of rows.

    Table Title

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

    Use a table title only if the title of the table is not indicated in the surrounding area.

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

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

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

    If you use a table title, show either a title for the table, with or without variant management, or an item count in the following format:

    Items (2,534).

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

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

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

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

    Selection

    Single Selection

    For single-selection master-detail scenarios within the flexible column layout, do not show an additional “navigated” indicator.

    Multiple Selection

    • We strongly recommend using the multi-selection plug-in. This ensures that all items selected using Select All or as part of a range are included – even if some items were not initially loaded in the front end. This is not the case if you use the multi-toggle option.
    • Do not limit the range selection for the multi-selection plug-in unless you have to.
      • If the dataset is small and/or completely available in the front-end, set the limit property to 0 to enable the Select All option and allow users to select any range.
      • If you have a large dataset, set a limit on the number of selected items to avoid performance issues. Also bear in mind that some actions won’t be helpful if the dataset is too big (for example, a delete operation on 2 million database entries).
    • If you set a limit, also display the corresponding message when the user selects more items at once than the limit allows (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification).
    Information
    When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

    • The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
    • The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

    • In multiple selection mode (multi toggle), do not show checkboxes in the first data column in the default delivery to avoid confusion.
    Don't
    Do not add checkboxes to the first data column in the default delivery
    Do not add checkboxes to the first data column in the default delivery
    • Never disable the selection checkbox. 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.

    Loading Data

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

    Grid table in busy state while loading data
    Grid table in busy state while loading data

    Errors and Warnings

    To indicate that the table contains items with errors or warnings, show a message strip above the table. On the message strip, provide information about errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

    To indicate an error in a single row, see Item States below.

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

    Developer Hint
    The sap.m.plugins.DataStateIndicator displays a message strip above the table, which shows binding-related messages.
    Table containing errors and warnings
    Table containing errors and warnings

    Columns – Best Practices

    Minimize the number of columns. Avoid the need to scroll horizontally in the default delivery.

    The grid table assigns the same width to each column by default. It is recommended that you overwrite this default to provide optimal space for your content (sap.ui.table.Column, property: width).

    If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the browser window size results in a scrollbar. After resizing a column, a scrollbar appears if the width of the table is not enough to show all columns. If the columns use less space than available, white space appears on the right side of the last column.

    If you define the column width as a percentage, resizing one column affects the width of several or all columns. Text becomes truncated when the browser window size is reduced. This is done to make sure that all columns together fill the space of the table. A scrollbar appears only in case the automatic change of the column widths is not enough for showing all columns. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum.

    If you define the column width as “auto”, the behavior is the same as for “percentage”. In contrast to percentage, “auto” distributes the columns equally.

    To decide on how to set the column width (pixel / rem / em vs. percent / auto), keep the following in mind:

    • For tables with only 2 to 3 columns, use pixel-based units. This ensures that on wide screens the values in the columns are not spread over the whole screen, which improves the readability of line items.
    • For tables with many columns, where a horizontal scrollbar is usually needed, use pixel-based units. This avoids unintended side effects when resizing columns.
    • For all other tables, use whatever fits your case better.

    Be cautious with mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it could also cause even more unexpected side effects when resizing a column. When using percentage-based widths for one or more columns, think of the possibility to not allow end users to resize columns at all.

    Optimize the column width for its initial visible content, including the column header texts. If this is not possible (for example, if showing the full texts would result in extremely wide columns), let the texts truncate. End users can change the width of the column to read the full text, as needed.

    Maintain a constant column width and avoid adjusting it automatically when the content changes.

    Always keep to one line of text. Do not wrap.

    Don't
    Don't truncate the initial visible content in the default delivery
    Don't truncate the initial visible content in the default delivery
    Don't
    Never wrap texts
    Never wrap texts

    Column Headers – Best Practices

    For each column, provide a label in the column header. In the default delivery, do not truncate the column header texts. Only let the text truncate if showing the full text would make the column too wide. Never wrap the text.

    Content Alignment

    For alignment of cell content, follow the guidelines below.

    Left-align the following: text, IDs, phone numbers, URLs, passwords, and email addresses.

    Left-alignment of text
    Left-alignment of text

    Right-align numbers (except IDs).

    This ensures comparability of numbers and amounts.

    Right-alignment of numbers
    Right-alignment of numbers

    Right-align amounts with currencies to the cell and align them in terms of their respective decimal points.

    This ensures that amounts with different currencies are shown correctly, whether these currencies have 0, 2, or 3 decimals.

    For aligning to the decimal point, use the sap.ui.uinified.Currency control.

    Alignment to decimal point
    Alignment to decimal point

    Right-align dates and times.

    This ensures comparability for most formats and locales.

    Right-alignment of dates
    Right-alignment of dates

    Left-align status information.

    Left-align status information
    Left-align status information

    Center-align icons.

    Left-align micro charts.

    XS micro charts in condensed mode
    XS micro charts in condensed mode

    Content Formatting

    Locale Settings

    Be locale-aware: show dates, times, numbers, and so on in the format corresponding to the user’s locale settings.

    Key Identifier

    Use a bold label or an emphasized link as the key identifier of an item. In the default delivery, show the key identifier in the first column.

    Emphasized link
    Emphasized link

    For strings with IDs, use one of the following options:

    • Show the ID in a separate column. Use this format if users need to sort, group, or filter by both the string and the ID.
    • Show the ID in parentheses after the corresponding string. In this case, you must opt for one criterion for sorting, filtering, and grouping – either the string or the ID. This option is then used for all sort, filter and group actions and can’t be changed later by the user. Use this format only if users don’t need to sort, filter, and group by both the string and the ID.
    Text and ID in two columns – Allows sorting, filtering, and grouping on both
    Text and ID in two columns – Allows sorting, filtering, and grouping on both
    If displayed as a link, use only the text as the link, not the ID
    If displayed as a link, use only the text as the link, not the ID
    Text and ID in one column – Sorting, filtering, and grouping available for either the text or for the ID, but not for both
    Text and ID in one column – Sorting, filtering, and grouping available for either the text or for the ID, but not for both
    Text and ID in one column - If displaying a link, show the whole string as the link (text and ID)
    Text and ID in one column - If displaying a link, show the whole string as the link (text and ID)

    Truncation

    Avoid truncation of typical content in the default delivery (sap.ui.table.Column, property: width). However, since the columns are resizable, do not worry too much if truncation occurs as columns can still be enlarged if necessary.

    To prevent adverse side effects when scrolling vertically, all line items must also have the same height. If you need to decide between truncation and different row heights, choose truncation. Do not wrap.

    Optimize column width for typical content, not all content
    Optimize column width for typical content, not all content

    Number of Links

    Are there too many links? Use subtle links to avoid a wall of links. Standard links are also emphasized more if they are surrounded by subtle links.

    Emphasized links, links, subtle links, and text
    Emphasized links, links, subtle links, and text

    Missing Value

    If there is no value for a cell, leave it blank. Do not display text as N/A.

    Leave empty fields blank
    Leave empty fields blank

    Numbering Items

    In terms of numbering items:

    • If the item number is more like an ID with regard to its description, use ID formatting as described above.
    • In all other cases, use a separate column for the item number.
    Add a separate column for the item number
    Add a separate column for the item number

    Status

    For status information, use semantic colors on the foreground elements.

    For status information on text, use an object status.

    Semantic colors on text
    Semantic colors on text

    Micro Charts

    Use only the following micro charts: Bullet, comparison, stacked bar. When using micro charts, use them in size XS.

    Micro charts in a grid table
    Micro charts in a grid table

    Empty Tables

    Avoid empty grid tables. If necessary, provide instructions on how to fill the grid table with data (sap.ui.table.Table, properties: noDataText, showNoData).

    Examples:

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

    Adapt the texts above if:

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

    Invalid State

    To show an invalid state of the grid table within the list report floorplan, show an overlay on the grid table and the corresponding toolbar (sap.ui.table.Table, property: showOverlay). The overlay prevents user interactions.

    Use this within the list report floorplan if filter settings have been changed but the grid table is has not yet been updated.

    Grid table with invalid data
    Grid table with invalid data

    Item States

    To show that an item has been modified, for example, within the global edit flow, add the string Modified in an additional column with the label Editing Status.

    In the default delivery, add a column directly behind the key identifier.

    A modified item
    A modified item

    To show that a modified item contains an error, for example, within the global edit flow, add the string Contains errors in the Editing Status column and highlight the row accordingly. This string replaces the Modified string.

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

    To show that an item is locked, add a transparent-style button with the corresponding icon and the text Locked by [name] in the Editing Status column.

    A locked item
    A locked item

    To show that an item is in draft state, add a transparent-style button with the text Draft in the Editing Status column.

    Item in draft state
    Item in draft state

    Show only one state at a time.

    Numbers and Units

    Show the unit of measurement in one of the following ways:

    Number and Unit in Same Cell

    The number and the unit are in the same cell. Do this if sorting, filtering, or grouping by the unit of measurement are not needed.

    For amounts, use a currency control to display the concatenated string.

    Number and unit of measurement in one cell
    Number and unit of measurement in one cell

    Number and Unit in Separate Columns

    The number and unit are in separate columns. Do this if sorting, filtering, or grouping by the unit of measurement are a common use case.

    Note that this column can be hidden or moved independently of the column containing the corresponding number. Therefore, be sure to have clear labels for both columns to communicate the dependency.

    Number and unit of measurement in two columns
    Number and unit of measurement in two columns

    Show the unit of measurment on the column header, if the unit of measurement is the same for all rows. If not, show the unit of measurement within the row.

    Drag and Drop

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

    Drop targets in between items
    Drop targets in between items

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

    Don't
    Do not combine rearranging items with sorting
    Do not combine rearranging items with sorting

    Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, 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. These are keyboard operable and available on all browsers.

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

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

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

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

    Context Menu

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

    The context menu can be triggered for the table, row, or cell. However, we do not recommend using context menus for cells: because the content of a cell is a different touch target than the cell itself, opening a cell context menu via touch is quite hard, even in cozy mode.

    Do not combine context menus with condensed mode: editable controls fill the entire space inside a cell. Because of this, context menus cannot be opened at all with touch or mouse interaction.

    Actions

    Multiple Items

    To trigger actions on multiple items, use a mutliselection grid table (sap.ui.table.Table, property: selectionMode, value: MultiToggle). Offer the corresponding actions in the table toolbar.

    Do not offer action triggering on multiple items if the table is generally expected to have fewer than 10 items. In this case, try to use the responsive table instead of the grid table.

    Single Item

    To trigger actions on a single item (sap.ui.table. Table, property: selectionMode, value: Single):

    • Show the actions on the table toolbar.
    • In rare cases, show the actions within the line item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. Provide a separate column per action. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

    To trigger navigation on line item level, choose one of the following options:

    • Use a link for the attribute that identifies the row. Clicking the link triggers the navigation.
    • Add the RowActions column and show the navigation indicator (  ) at the end of the row. The navigation arrow triggers the navigation.

    Special case: Multi-selection in a master-detail scenario
    When a multi-selection table is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case, you can display a “navigated” indicator to show which item is currently open.

    Use the RowActions column only for one or both of the following actions:

    • Navigate to details page ( )
    • Delete ( )

    The RowActions column does not provide a column header text. It is fixed and will not scroll away. Users also cannot personalize this column.

    Navigate to details page
    Navigate to details page

    Single Cell

    To trigger actions on a single cell, create the corresponding click event. Do not use the cell click event if the cell contains interactive controls, such as links.

    Add Items

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

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

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

    Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

    There are three options for adding an item. 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 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.

    Depending on the flow, an item can be in one of three different states:

    • New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
    • Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the table. Ignore current sort, filter and grouping criteria to keep the item visible.
    • Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
      • Inline creation: After Save was triggered on the table toolbar or at page level.
      • Create with dialog: A table showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

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

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

    Enabling/Disabling Actions

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

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

    For more details, see UI Element – States.

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

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

    Editable Content

    For editable content, only use the following controls, and only one control per cell:

    Only these controls are optimized for all viewing modes of the grid table.

    If you need edit mode, change your text controls, such as label, text, link, object status, icons, and currencies, to editable controls as soon as you switch to edit mode, but not before. You can do this by exchanging the controls, for example, from sap.m.Text to sap.m.Input.

    For mass editing items:

    • Provide multiselection.
    • Provide an Edit button.
    • If several items are selected, clicking the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

    For more information, see Mass Editing.

    Interactive controls – In line
    Interactive controls – In line

    View Settings

    There are several ways to show Sort, Filter, and/or Group settings:

    • Column header menu: In all cases, show the corresponding settings in the column header menu.
    • View settings dialog: Simple and more flexible with regard to filter settings. No advantage for sorting. Allows the user to ungroup grouped columns.tables with a medium amount of items.
    • Table personalization dialog: Provides complex options for sorting items by several levels and allows the user to ungroup grouped columns. It also provides a query-builder-like approach for filter settings. The complexity of the options is also its downside. Use the table personalization dialog for tables with a large number of items.
    • If filtering is a main use case, use the filter bar. In this case, avoid offering additional filter settings on the table. If you do, the filter settings on the grid table work only on the result set provided by the filter bar.

    Always be careful when synchronizing the settings in the dialog with the settings from the column header menu.

    Trigger the dialogs in one of the following ways:

    • View settings dialog: Provide several buttons, one for each of these view settings. Each button opens the view settings dialog on the corresponding page.
    • P13nDialog: Provide a settings button, which opens the table personalization dialog containing all pages.

    Use only the view settings you really need. For example, do not offer grouping if it does not support your use case.

    Column header menu with view settings
    Column header menu with view settings
    Table toolbar with triggers for view settings dialog
    Table toolbar with triggers for view settings dialog
    Table toolbar with trigger for table personalization dialog
    Table toolbar with trigger for table personalization dialog

    Be persistent. When reopening the app, show the analytical table in the same view settings (sort/ filter/ group/ aggregation settings) as last defined by this user.

    Sort

    Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the first column in the default delivery.

    To display the current sort state, an icon is shown in the column header of the most recently sorted column. This icon indicates the sort direction (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

    For the default sort settings, sort by the column that identifies the row, which is usually the first column in default delivery.

    Column, sorted ascending
    Column, sorted ascending
    Column, sorted descending
    Column, sorted descending

    The descending sort order must always be the exact reverse of the ascending sort order. For each column, provide a meaningful sort order. For example:

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

    Filter

    To display the current filter state, an icon is shown in the column header of the filtered column (sap.ui.table.Column, properties: filtered, filterProperty, filterValue, filterOperator, defaultFilterOperator, filterType).

    Column, filtered
    Column, filtered

    Group

    To display the current group state, group headers are shown. Show the following text in the group header:

    [Grouping value] – [Item count for the group]

    Group headers
    Group headers

    In general, offer reasonable grouping by default if appropriate. Enable the user to ungroup via the view settings dialog or via the table personalization dialog.

    Personalization

    Only offer personalization if you need more columns than those that fit on a tablet screen, which is usually five, to fulfill 80% of your main use cases.

    Persist the column layout. When a user reopens the app, show the grid table with the same column layout settings as last defined by this user.

    Add, Remove, and Rearrange Columns

    To add, remove, or rearrange columns, use one of the following:

    • The table personalization dialog: It offers some simple settings for column layout. Use this if you have only a few columns to choose from and/or you use the view settings dialog.
    • The p13n dialog: Besides various complex view settings, it also provides settings for column layout. Use this if you have a large number of columns to choose from and/or you use this dialog anyway for view settings.

    In both cases, trigger the dialog via the settings button in the table toolbar. As short cut, use Ctrl+comma.

    You can also use drag and drop to rearrange columns (sap.ui.table.Table, property: enableColumnReordering). If you allow rearranging via drag and drop as well as via a dialog, keep both places in sync.

    Resize Columns

    Resizing columns works differently on touch and non-touch devices.

    • Non-touch devices: Drag and drop the column separator on the right side of the column. Double-clicking the column separator optimizes the width of the column to the data currently loaded into the front end, which is usually about 100 rows.
    • Touch devices: Clicking the column header reveals two buttons: one for opening the column header menu, another one for resizing the column. Drag and drop this second button to resize the column.

    Freeze Columns

    To freeze columns, offer the setting in the column header menu (sap.ui.table.Table, property: enableColumnFreeze). Selecing Freeze on a column freezes all columns from the first one to the one where Freeze is selected. On this column, the menu entry changes from Freeze to Unfreeze.

    Frozen column
    Frozen column

    Highlight Items

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

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

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

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

    (sap.ui.table.Table, aggregation: rowSettingsTemplate)

    Highlighted items
    Highlighted items

    Tables in Object Pages

    In the object page, we advise against using the analytical, grid, and tree tables. Instead, use a responsive table and offer navigation to a list report with the table types mentioned above.

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

    Export to Spreadsheet

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

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

    Paste

    The browser paste function can be used to paste data from the clipboard to the table (Ctrl+V or browser context menu).

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

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

    Properties

    sap.ui.table.Table

    The following additional properties are available for the grid table:

    • The property: width defines the width of the grid table.
    • The property: rowHeight defines the height of each row in the grid table. Since the height required is calculated automatically by the grid table, this property is only needed rarely.
    • The property: columnHeaderHeight defines the height of the column headers. Since the height required is calculated automatically by the grid table, this property is only needed rarely.
    • The property: columnHeaderVisible can be used to hide the column headers. Always show the column headers.
    • The property: showColumnVisibilityMenu provides an additional entry in the column header menu that allows columns to be shown or hidden. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
    • The property: visibleRowCount defines the height of the grid table. Show as many rows as fit on the screen.
    • The property: visibleRowCountMode defines whether the height of the grid table is fixed or automatically calculated based on the space provided by the underlying container. For automatic calculation, make sure that all rows have the same height.
    • The property: minAutoRowCount defines the minimum number of rows that must be shown if the property: visibleRowCountMode is set to “auto”. Show at least three to five rows.
    • The property: firstVisibleRow defines the first row shown in the visible area of the grid table. The grid table is scrolled accordingly.
    • The property: allowColumnReordering is deprecated. Do not use it. Use the property: enableColumnReordering instead.
    • The property: editable does not have a visible effect. Do not use it.
    • The property: enableGrouping turns the experimental grouping on or off. Handle with care.
    • The property: enableCustomFilter changes the filter entry in the column header menu from an edit box to Filter…. Selecting this entry throws an event to which apps can react, for example, by opening a dialog. In general, you should choose the built-in filter over your own implementation. Specifically, keep filtering via the column header menu simple, while offering more advanced options via the table personalization dialog.
    • The property: enableBusyIndicator has not yet been fully implemented. Do not use it.
    • The property: title adds a line of text on top of the grid table. Do not use this. To add a title to the table, use a toolbar.
    • The property: footer adds a short text at the bottom of the table.
    • The property: Busy sets the grid table to busy state. While in busy state, the whole table cannot be used and items cannot be read due to an overlay.
    • The property: Tooltip does not have an effect. Do not use it.
    • The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). Do not use it.

    sap.ui.table.Column

    The following additional properties are available for the column:

    • The property: visible defines whether a column is shown or hidden.
    • The property: name defines the name shown in the column header menu for showing and hiding columns. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
    • The property: headerSpan defines whether one column header is used for one or several columns. To prevent adverse side effects, always use one column header for only one single column. Do not use this property.
    • The property: Tooltip does not have an effect. Do not use it.

    Resources

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

    Elements and Controls

    Implementation

    Smart Table

    Intro

    The smart table creates a responsive table, grid table, tree table, or analytical table based on an OData (Open Data Protocol) service and its annotations. The table toolbar comes with additional built-in features, such as personalization, export to spreadsheet, and variant management.

    When to Use

    Use the smart table if:

    • You use an OData service for your app (OData version 2 only).
    • The feature set of the smart table fits for your app. In this case, the smart table is faster to implement.
    • You need more than one of the major features of the smart table. Otherwise, you might not benefit from a shorter implementation time. For example, if you just need the export to spreadsheet feature, creating a responsive table directly is usually faster than using the smart table.

    Do not use the smart table if:

    • You use a different technology to OData version 2. Use the corresponding table control directly.
    • You need more flexibility in the content design, such as several different row templates or less complex personalization features. Use the responsive table directly.
    • You do not have complex data. Another control like a select, combo box, list, grid list, tree, or smart list might do the job better.
    • You have very complex data. Did you check the chart?
    • Users need to switch between a chart and table. The smart table is not designed to work inside an existing chart container. In this case, use either the smart chart or the corresponding table directly.
    • You need to layout different controls in a table-like grid. Use a flexible grid instead.
    • You need to layout different input fields with labels. Use a form, simple form, or smart form.

    Components

    The smart table consists of a table toolbar (1), an infobar (2), and a table (3).

    The components of a smart table
    The components of a smart table

    Table Toolbar

    Toolbar with all features provided by the smart table out-of-the-box
    Toolbar with all features provided by the smart table out-of-the-box

    The table toolbar is generated automatically. The following toolbar content is provided by the smart table out-of-the box:

    1. Title
    2. Item counter
    3. Variant management
    4. Show Details / Hide Details
    5. View Settings
    6. Export to Spreadsheet
    7. Maximize / Minimize

    In addition, you can add app-specific actions.

    Title

    The title is optional (property: header).

    Guidelines
    Add a title whenever the title is not indicated in the surrounding area.
    Developer Hint
    If you don’t provide a title, ensure that you support screen reader users: create a simple table in the XML view, use ariaLabelledBy to point to the corresponding text, and add this table to the smart table. Make sure that the table type within the smart table is set accordingly. The smart table will take care of the rest (creating columns, and so on).

    Item Counter

    The item counter is optional and only available if you show a title (property: showRowCount).

    Guidelines
    Show the item counter together with the table title, unless:

    Variant Management

    Variant management is optional (properties: persistencyKey, useVariantManagement, currentVariantID, association: smartVariant).

    Guidelines
    Use variant management only if really needed.

    Show Details / Hide Details

    Show Details / Hide Details is mandatory with and only available for the responsive table. Columns with a low priority (low or medium priority on phones) are hidden in the pop-in area (properties: demandPopin, showDetailsButton, annotation: UI.Importance). You can define which column priority levels are hidden (property: detailsButtonSettings). The button only appears if there are corresponding columns in the pop-in area.

    Details hidden
    Details hidden
    Details shown
    Details shown

    View Settings

    View Settings are optional. The button triggers a P13n Dialog (property: useTablePersonalisation). The View Settings dialog can also be opened with the shortcut Ctrl+Comma.

    Guidelines
    Offer view settings only if they are really needed. Tables with just a few columns and rows do not need to be sorted, filtered, or grouped.

    Sort and Filter

    Sorting, filtering, and column settings are automatically available for all columns in all tables. For single columns, you can remove the sort and filter settings (annotations: SortRestrictions, FilterRestrictions).

    • The current sort state and sort order is displayed as an icon in the column header of the sorted columns.
    • The current filter state is displayed as follows:
      • In the responsive table, an infobar is shown if filters have been set in the table personalization settings.
      • For all other tables, filtering is indicated by an icon in the column header of each filtered column.

    When amounts with different currencies appear in a single column, you can change the sort behavior to sort these columns first by currency, then by amount (annotation: ApplyMulitUnitBehaviorForSortingAndFiltering). This behavior is applied for all such columns in the smart table. It cannot be defined per column.

    Guidelines

    • Do not turn off the info bar (property: useInfoBar).
    • In the default delivery, sort items in a meaningful order. This works only for the grid table, tree table, and analytical table. You can also provide default filter settings (all tables) and grouping (responsive table and analytical table only) (annotation:
      PresentationVariant).
    • If the smart table is used together with a filter bar (property:
      smartFilterId), do not offer filtering for the smart table itself.

    Developer Hint
    The smart table can be linked to a smart filter bar. If linked, the filter bar settings are automatically applied to the smart table (sap.ui.comp.smarttable,SmartTable, property: smartFilterId).

    Group

    Group settings are only available for the responsive table (all columns, one level only) and the analytical table (dimension columns only, multiple levels).

    The following text is usually shown on the group header:
    [Label of the grouped column]: [Grouping value]

    Within the analytical table, the grouped column remains visible by default if it is grouped using the P13n Dialog. The column is hidden if it is grouped using the column header menu.

    Guidelines
    In some cases, the group header text may not be shown automatically as described. This applies to special cases in the analytical table (for example, if the displayed text is not taken directly from the data source), as well as custom columns in both responsive and analytical tables. In such cases, you must set and format the group header text yourself.

    Column Settings

    Column settings are used to show and hide columns. For the grid table, tree table, and analytical table, the column settings automatically enable resizing via the column header and size-to-fit for text-only columns (double-click on column separator line).

    Guidelines
    If sorting, grouping, and/or filtering are needed, also show the column settings (sap.ui.comp.smarttable.SmartTable, property: useTablePersonalisation).
    Developer Hint
    Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

    Export to Spreadsheet

    Export to Spreadsheet is optional. The button triggers either a front-end export using the export to spreadsheet utility, or a back-end export via Gateway (properties: useExportToExcel, exportType). The front-end export allows for additional settings and can also be triggered with the shortcut Ctrl+Shift+E.

    Guidelines

    • Only offer the Export to Spreadsheet option if your end users typically export the data shown in the table 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, tables with only a few items, shopping carts, or data that does not need to be analyzed.
    • If you offer the Export to Spreadsheet button, use the front-end export.
    • If your table has columns with non-textual content, provide a textual equivalent for those columns. Non-textual content is not exported.

    Warning
    With both methods, the file size is limited by the available browser memory. As a result, exporting large tables can lead to memory overflows and crash the export process.

    Apply the following size restrictions as a rule-of-thumb:

    • For the front-end export, do not export more than 2 million table cells on desktop browsers or 100,000 table cells on tablets and phones.
    • For the back-end export, do not export more than 100,000 table cells.

    For larger tables, consider using custom-built, specialized export solutions instead.

    Maximize / Minimize

    Maximize / Minimize is optional. It allows users to show the table in full screen mode and to exit full screen mode (property: showFullScreenButton).

    Guidelines

    App-Specific Actions

    App-specific actions can only be added using a custom toolbar (aggregation: customToolbar).

    Developer Hint

    Infobar

    Infobar with filter information
    Infobar with filter information

    The infobar is only available for the responsive table. It indicates which filter settings are currently active. If no filters are set, the infobar is hidden (property: useInfoToolbar, value: Auto).

    Guidelines

    Table

    Responsive table within a smart table
    Responsive table within a smart table

    The table is generated automatically. The sections below describe the behavior and different possibilities:

    Table

    The table provides the following features:

    Guidelines

    • Use the responsive table wherever possible. Use the other table types only if really needed. If you use another table, provide a fallback solution for phones.
    • For the responsive table, the smart table initially loads 20 items and shows a More button for loading additional items. Change this behavior if:
      • You expect fewer than 200 items. Load all items from the start (sap.m.Table, property: growing).
      • You expect more than 200 items. Adapt the number of items initially loaded to cater for large screens, and load additional items automatically when the user scrolls down (sap.m.Table, property: growingScrolllToLoad).

    Developer Hint
    To change the growing behavior, create a responsive table with just the settings for the growing behavior, and hand it over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on).
    Developer Hint

    • The property tableBindingPath defines the path from which the data is fetched.
    • The property enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

    Developer Hint
    To change the selection mode, add a navigation indicator to single rows, or add a highlight to specific rows, you need to create a table with the corresponding settings. You do not need to define anything else. Hand this table over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on). This method allows you to use the multi-selection plug-in with the grid table, tree table, and analytical table.

    Column Visibility

    • Columns are created automatically. Items are rendered based on the properties and metadata of the underlying OData service (annotation: LineItem, properties: entitySet, tableBindingPath, initiallyVisibleFields, ignoreFields). A column is generated for each OData entity property.
    Developer Hint
    If a column needs to be in the model but should not be shown, you can hide it from both the table and the P13n dialog (property: ignoredFields, annotation: UI.Hidden).

    Use this option if:

    • A column is needed to provide an ID that is used for navigation purposes only. However, you only want to display the corresponding text on the UI, and not the ID.
    • The values of a column are needed to perform calculations, but only the results are shown on the UI.

    You can use the property requestAtLeastFields to request additional (technical) columns with every request, regardless of whether these columns are currently visible. This does not work with the analytical table.

    The property ignoreFromPersonalization is only available with the analytical table. It loads additional key fields that are needed for aggregations but are never visible.

    Developer Hint
    Columns can be removed at runtime. This is useful if the same table is used for similar, but slightly different objects. For one of the objects, specific columns need to be shown, for others they must be hidden, and users must not be able to add them in the personalization settings (function: deactivateColumn).
    • You can define which columns are initially visible when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleFields).
    Guidelines

    • Keep the number of initially visible columns to a minimum. Avoid pop-in behavior (responsive table) or horizontal scrolling (all other tables) on a tablet screen size in the default delivery (annotation: PresentationVariant/ LineItem).
    • Also keep the number of additional columns offered in the personalization settings to a minimum. You can use the P13n dialog to let users 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 each column that is initially visible, the LineItem annotation includes a DataField record, which allows you to influence the content rendering of the smart table.
      For columns that are initially invisible, the content rendering can also be influenced via the annotation DataFieldDefault.
    Developer Hint
    If the same column is defined via LineItem and via DataFieldDefault, LineItem wins.

    Column Layout

    • A default column width can be calculated for each column based on the data type, the column label, the edit/read-only state, and the annotations: textArrangement, MaxLength for strings, Precision and Scale for numeric data (property: enableAutoColumnWidth).
      The calculated width is between 3 rem and 20 rem. Apps can change this default width if needed (annotation: CSSDefaults).
      If the combined width of all the columns is less than the width of the table, the remaining space stays empty.
    Guidelines
    Choose a column width that avoids truncation for the initial data and (if feasible) for the column header label. If the default column width doesn’t fit, change it.
    Developer Hint
    For the responsive table, enableAutoColumnWidth also applies the following changes:

    • The smart table property demandPopin is set to true.
    • The responsive table property fixedLayout is set to Strict.
    • The responsive table property contextualWidth is set to Auto.
    • Column resizing is enabled for all columns (including custom columns).
    • Labels in the column headers no longer wrap. If there is not enough space, they truncate.

    In this case, the properties above must not be managed by the app.

    Responsive table with automatically calculated column widths, resizing, and remaining space
    Responsive table with automatically calculated column widths, resizing, and remaining space
    • If the automatically generated content does not fit for your use case, you can override the automatic behavior with your own column template.
      You can also add further columns. This allows you to provide columns with app-specific or inline actions, columns which show calculated values (based on more than one OData entity property), or – for responsive tables – columns that show more than one control.
    Developer Hint
    To add or override columns (“custom columns”):

    • Use an XML view to define the underlying table with just the columns to be added/overridden.
    • To override columns, provide the column key of the column you want to exchange.
    • Add this “unfinished” table to the smart table. The smart table adds all the automatically generated columns and additional features.

    Make sure that the sortProperty and the filterProperty are set (define p13nData via the aggregation CustomData). If you offer the export to spreadsheet option,  ensure that it works as expected.

    If you are using a responsive table, also make sure that the responsive behavior for this column works as expected (sap.m.Column, property: importance).

    Column Headers

    • You can specify a column header text for each column (annotation: sap:label).
    Guidelines
    Provide a column header text for each column. (annotation: sap:label).
    • The column headers contain the following settings:
      • Sort Ascending, Sort Descending
      • Filter: Opens the P13n Dialog. If this does not fit for your use case, exchange this menu item (property: enableCustomFilter)
      • Group (only analytical table, only on dimension columns)
      • Total (only analytical table, only on measure columns): This setting is not persisted (annotation: sap:aggregation-role, value: measure).
        If a column contains entries with different units of measurement, a Show Details link appears instead of the total. Clicking the link opens a popover showing the subtotals per unit of measurement.
      • Freeze (only available for grid table, tree table, and analytical table): Must be added manually.
    Guidelines
    Offer column totals by default for all columns where totals make sense (annotation: PresentationVariant).
    Developer Hint
    To add a Freeze option manually, declare the corresponding table inside the smart table in the XML view, and use the corresponding settings for this inner table.

    Clicking the column header reveals sort and filter options (responsive table)

    • Smart Table - Column Header - 1.90
    Column header menu for a dimension column of an analytical table within a smart table
    Column header menu for a dimension column of an analytical table within a smart table
    Column header menu for a measure column of an analytical table within a smart table
    Column header menu for a measure column of an analytical table within a smart table

    Content

    The smart table offers the following options for creating columns automatically:

    1. You can render the smart table in either read-only or edit mode (with no option to switch), or allow users to switch between the two modes (properties: editable, useSmartToggle).
    2. In read-only or edit mode, the smart table renders the controls as listed in the table below, or uses the smart field for both modes. If you use smart fields together with the option to switch between read-only and edit mode, the smart table renders the read-only controls as in the list below, but uses the smart field for edit mode. The smart field limits the rendering options (aggregation: customData, key: useSmartField), but also allows for:
      • Better control of the visibility of a field per row (smart field, annotation: FieldControl)
      • Use of value help for input fields
    Developer Hint
    From a performance perspective, using the smart field is more expensive than using the controls provided by the smart table directly. With this in mind, follow the rules below:

    • For read-only tables, use the controls provided by the smart table.
    • For simple editing cases with no need for FieldControl or value help on input fields, use the controls provided by the smart table.
    • For more complex editing cases, use smart fields.
    • For switching between read-only and edit modes:
      • In read-only mode, use the controls provided by the smart table.
      • In edit mode, use either smart fields or the controls provided by the smart table, based on the guidance above.

    In cases where the controls are rendered by the smart table, the following controls are used:

    Read-only Edit Annotations / Edm type Comment
    Static text Text Input field Edm.String
    Decimal numbers Text Input field Precision, Scale, Edm.Byte, Edm.Decimal, Edm.Double, Edm.Int16, Edm.Int32, Edm.Int64, Edm.SByte, Edm.Single
    Status information Object status or Icon Input field Criticality, CriticalityType,
    CriticalityRepresentationType    		 Do not use editable status information.
    Key identifier Object identifier (responsive table)
    Text
    (all other tables)    		 Input field for the ID SemanticKey,
    Common.EditableFieldFor
    Text and ID Text, object status, or object identifier Input field for the ID TextArrangement Use together with the annotation mentioned above for static text, status information, or key identifier.

    Sorting, filtering, and grouping only works for the ID, even if the ID is not displayed.
    Links with/without quick view Smart link Smart link SemanticObject Smart links can be customized using the aggregation: semanticObjectController
    Dates Text Date picker Edm.DateTime, sap:display-format, value: date, IsCalendarDate
    Dates and times Text Date/time picker Edm.DateTime, Edm.DateTimeOffset
    Times Text Time picker Edm.Time
    Fiscal periods Text Input field IsFiscalYear, IsFiscalPeriod, IsFiscalYearPeriod, IsFiscalQuarter, IsFiscalYearQuarter, IsFiscalWeek, IsFiscalYearWeek, IsDayOfFiscalYear
    Amounts with currencies Two text controls Input field for the amount sap:semantics, value: currency-code In edit mode, the currency is shown as static text next to the input field.
    Phone numbers Link Input field IsPhoneNumber Opens the system application for making phone calls.
    Email Link Input field IsEmailAddress Opens the system application for writing emails.
    Pictures Image Input field IsImageURL Only available for the responsive table. In edit mode, the input field contains the URL to the image.
    Boolean Text Checkbox Edm.Boolean For read-only, the displayed text is Yes or No.

    In all cases, the smart table automatically takes care of the content alignment and formatting (except for custom columns).

    Input fields can be accompanied by a value help dialog (annotation: ValueList). If annotated, triggering the value help button opens a value help dialog. Within this dialog, you can provide a search field (annotation: ValueList, property: SearchSupported).

    If no ValueList annotation is provided, you can restrict the number of characters for an input field (annotation: MaxLength).

    You can provide additional controls, such as micro charts, rating indicators, progress indicators, and buttons, as custom columns (using an XML view). For custom columns, you must provide any read-only and editable content manually.

    Guidelines
    For inline actions, use a text-only or an icon-only button. Make sure the icon communicates the function clearly enough. Otherwise, use a text-only button.

    If the smart table is used with the responsive table, you can show the status of an item by displaying a highlight indicator on the left of the item (property: highlight).

    Behavior and Interaction

    The behavior is generally inherited from the underlying table, toolbar, variant management, export to spreadsheet, 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.

    Empty Tables

    If there is no data to show, the smart table renders a default text. This text can be overwritten by the app development team. The default texts are:

    • If a table is initially empty:
      No items available.
      Overwrite this whenever a hint can be provided on how to fill the table with data.
      (property: initialNoDataText, value: $NO_FILTERBAR)
    • 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.
      (property: initialNoDataText, value: $FILTERBAR)
    • 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.
      (aggregation: noData, changeable at runtime)
    • If the user has hidden all of the columns in the personalization settings, the following text is shown:
      Right now, there are no visible columns in the table. Please select the columns you need in the table settings.
      This text cannot be changed.
    Guidelines

    • For all other cases, provide instructions on how to fill the table with data (aggregation: noData).
    • The “no data” text can be exchanged at runtime. Use specific texts for different situations.
    • Avoid displaying a table without any items, especially when the app is initially loaded.

    An empty smart table
    An empty smart table

    Errors and Warnings

    To indicate that the table contains items with errors or warnings, the smart table can show a message strip above the table (aggregation: dataStateIndicator). On the message strip, information about errors or warnings is provided, as well as the possibility to filter down the table to the corresponding rows. When issues are solved or when new issues appear, the message strip is updated accordingly.

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

    Table containing warnings
    Table containing warnings
    Table containing errors and warnings
    Table containing errors and warnings
    Guidelines
    To show that an item contains an error,

    Developer Hint
    Binding-related messages are shown automatically.

    Responsiveness

    The smart table acts exactly like the embedded controls. For details see:

    • Toolbar Overview
    • Infobar
    • Responsive Table via auto pop-in mode
      (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true).
      You can use the UI.Importance annotation to influence the priority of each column.
      You can provide a Show Details button to let users show/hide columns with low importance (property: showDetailsButton).
    • Grid Table, Tree Table, Analytical Table:
      These controls are not intended for use on smartphones. If you use a smart table with this configuration, ensure that you implement a fallback solution for small screens.
    Guidelines
    If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true). Ensure that the most important columns stay in the tabular layout as long as possible (annotation: UI.Importance). 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.

    Developer Hint

    • To change the layout of the pop-in area (Block, GridSmall, GridLarge), you need to create a responsive table with the corresponding settings (property: popinLayout). You do not need to define anything else. Hand this responsive table over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on).
    • Do not use the annotation UI.Importance together with the grid table, tree table, or analytical table. It hides columns with low priority on phones or narrow-width screens, without the possibility to show them again.

    Examples

    Responsive table within a smart table
    Responsive table within a smart table
    Grid table within a smart table
    Grid table within a smart table

    Top Tips

    • If you are using the responsive table, enable and configure the auto pop-in mode and use the Show Details / Hide Details button.
    • For custom columns, follow the guidelines of the respective table. If needed, use responsive paddings for aligning the content.
    • Enable only the features that are needed for your use case. Very small tables do not need to be sorted, filtered, grouped, and rarely exported. Don’t just add unnecessary features for consistency purposes.
    • If the page has a filter bar, don’t offer filtering for the table.
    • If you are using custom columns, make sure that any export and personalization features you are using also work for these columns.

    Properties

    The following properties are available for sap.ui.comp.smarttable.SmartTable:

    • The property: toolbarStyleClass is deprecated. Do not use it.
    • The property: useOnlyOneSolidToolbar is deprecated. Do not use it.

    Related Links

    Elements and Controls

    Implementation

    Table Personalization Dialog

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

    Usage

    Use the table personalization dialog if:

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

    Do not use the table personalization dialog if:

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

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

    Responsiveness

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

    On smartphone devices, always display the table personalization dialog in full screen mode.

    Smartphone - Size S
    Smartphone - Size S
    Tablet - Size M
    Tablet - Size M
    Desktop - Size L/XL
    Desktop - Size L/XL

    Layout

    Position on the Screen

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

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

    Layout of the Dialog

    The table personalization dialog comprises the following five areas:

    (1) Header

    (2) Toolbar

    (3) List Header

    (4) Column list

    (5) Footer toolbar

    Table personalization dialog – Overview
    Table personalization dialog – Overview

    Components

    The table personalization dialog contains the following sections:

    Dialog Header

    The header displays the dialog title and the Reset button to revert to the initial state.

    Dialog header
    Dialog header

    Toolbar

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

    Toolbar
    Toolbar

    List Header

    The list header displays the Select All checkbox for selecting all columns.

    List header
    List header

    Column list

    The column list displays the available columns. The user can filter the selection using the search field in the toolbar.

    Column list
    Column list

    Footer toolbar

    The footer toolbar displays an OK and a Cancel button.

    Footer toolbar
    Footer toolbar

    Behavior and Interaction

    The table personalization dialog is resizable.

    Open the Dialog

    To open the table personalization dialog, the user clicks the  (Settings) button on the right-hand side of the table toolbar.

    Table with settings button
    Table with settings button
    Table personalization dialog opened
    Table personalization dialog opened

    Show or Hide Columns

    To show or hide columns, the user selects or deselects the checkbox for a column (list item).

    The column is hidden in the table
    The column is hidden in the table
    The column is visible in the table
    The column is visible in the table

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

    Show all
    Show all
    Hide all
    Hide all

    Move Columns

    Users can change the order of the columns in the table using the   (Move Column Up) and   (Move Column Down) buttons in the toolbar.

    To change the order, click an item (not on the check box, but on the rest of the line), and click the button: Items on top are farthest to the left in the table, items on bottom are farthest to the right.

    Move buttons
    Move buttons
    The column 'Supplier' will be moved. It is not checked, though, therefore the result of moving this column will not be visible in the table.
    The column 'Supplier' will be moved. It is not checked, though, therefore the result of moving this column will not be visible in the table.

    Search/Filter Columns

    Users can search for or filter columns using the search field in the toolbar.

    Search field
    Search field

    The search is a live search (also known as “search-as-you-type”), which is triggered by each character the user enters or deletes. For more information, see search.

    To clear the filters, the user can delete all characters manually, or use the  icon.

    The list then shows all columns again.

    Search while you type
    Search while you type

    Reset Personalization

    The Reset button in the dialog header resets all settings to the initial state.

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

    Reset button
    Reset button

    Confirm/Cancel Changes

    The changes are applied when the user closes the dialog with the OK button.

    The Cancel button closes the dialog without applying the changes.

    OK and Cancel buttons
    OK and Cancel buttons

    Resources

    Elements and Controls

    Implementation

    Tree Table

    A tree table contains a hierarchical set of data structured in rows and columns and grouped into nodes. The analytical table (also know as ALV) can provide additional details in several non-hierarchical columns per line item. 

    Usage

    Trees are used to display and work with large amounts of hierarchical data. They have a high data density and therefore convey an immediate feeling of complexity. Ideally, you should only show trees with a lot of hierarchical data as a last resort. Try the following instead:

    • Break down the data into manageable chunks and allow the user to navigate or drill down between them.
    • Use charts with drilldown functionality until the amount of data is more manageable.

    Responsiveness

    A tree table is available for desktops and tablets, but not in smartphone sizes. It supports touch devices, but is not optimized for small screens.

    If you use a tree table, note that you have to implement a fallback solution for small screens. This fallback solution does not need to support all use cases.

    Possible fallback solutions are as follows:

    • Use navigation to different pages instead of a tree structure. This works well for structures that are no more than four levels deep.
    • Remove levels until only one or two remain. Replace a single-level tree by a table, and a two-level tree by a grouped table or a split-screen layout.
    • Use filtering instead of a tree structure.

    You can try to create a fallback based on these ideas, but a completely different solution, such as showing charts in a read-only case, might be more appropriate.

    Tree table shown on a desktop
    Tree table shown on a desktop
    Tree table shown on a tablet
    Tree table shown on a tablet

    Types

    Like all SAP Fiori controls, the tree table is shown in compact mode on a desktop and in cozy mode on tablets.

    For a desktop, you can also display even more rows on the same screen height by adding the condensed mode in addition to the compact mode. This renders less white space for each item.

    Note that the condensed content density has always to be set in addition to compact. Do not use condensed on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable and / or unwanted results, e.g. cozy sized controls in condensed sized containers, missing padings, etc.

    Note that neither compact mode nor condensed mode can be interacted with touch. Even on a desktop with a touch screen, users will have difficulty selecting rows or using controls inside the cells when using their fingers.

    Furthermore, condensed mode is not available for Internet Explorer 9. If condensed mode is to be used, please provide a fallback.

    For more information on cozy and compact modes, see content density.

    Compact Mode

    Tree table – Compact mode
    Tree table – Compact mode

    Condensed Mode

    Tree table – Condensed mode
    Tree table – Condensed mode

    Components

    Column Header

    The column header provides the label for the corresponding column and access to the column header menu.

    Resizing columns works in the following ways:

    • Mouse interaction: Dragging the separator line between two columns (sap.ui.table. Column, property: Resizable). Double-clicking optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable).
    • Touch interaction: The user taps the column header to reveal two buttons: one for showing the column header menu and one for resizing. Drag the latter to resize the column.
    • Keyboard interaction: The width of the focused column header can be increased with Shift+Right and decreased with Shift+Left.

    After resizing a column, the adaptation of the column widths depends on how the column width is set:

    • If column widths are set in pixel-based units (px, em, rem), the corresponding column is adapted and following columns are moved accordingly. The width of all other columns is not affected.
      If all the columns together take up less width than the table control, an empty space is added. If all the columns together take up more width than the table control, a scrollbar appears.
    • If all column widths are set in percentage or “auto”, resizing one column might also lead to the automatic resizing of some or all other columns. The position of the resized column might also be affected. This is done to ensure that the whole table width is used and no white space is added. A scrollbar appears only, if all or most of the columns get very small. To avoid the unintended side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

    Columns can be rearranged by dragging the column header to another position (sap.ui.table.TreeTable, property: enableColumnReordering). Keyboard: the focused column header can be moved by one position to the corresponding direction with Shift+Left / Shift+Right.

    Tree table – Column header
    Tree table – Column header
    Opening the column header menu on touch devices
    Opening the column header menu on touch devices
    Fewer columns than space available
    Fewer columns than space available

    Line Item

    A line item contains a set of cells and provides options for selecting the item.

    To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.TreeTable, property: rowHeight).

    Tree table – Line item
    Tree table – Line item

    In rare cases, show the actions within the line item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. Provide a separate column per action. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

    Tree Column

    The first colum (tree column) provides the hierarchical structure.

    Tree table – Tree column
    Tree table – Tree column

    Expand/Collapse Button

    The expand/collapse button is offered on container nodes to allow the child items of the corresponding container to be shown or hidden.

    Tree table – Collapse
    Tree table – Collapse
    Tree table – Expand
    Tree table – Expand

    Container Node

    A container node is a line item that contains child elements.

    Tree table – Container node
    Tree table – Container node

    Leaf Node

    A leaf node is a line item that does not contain child elements.

    Tree table – Leaf node
    Tree table – Leaf node

    Cell

    Each cell provides one data point. It can contain one of the following controls to display the data point:

    While it is technically possible to also use other controls, doing so could lead to issues in regards to alignment, condensed mode, screen reader support, and keyboard support.

    If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false).

    Tree table – Cell
    Tree table – Cell

    Tree Cell

    A tree cell is a cell inside the tree column. Besides its data point, it provides a collapse/expand button on container nodes, and it indents the different hierarchy levels.

    Tree table – Tree cell
    Tree table – Tree cell

    Column Header Menu

    For the tree column, the column header menu can contain the menu item Freeze and a Filter field, in which the user enters free text.
    For all other columns, only the free text filter is available.

    Tree table – Tree column header menu
    Tree table – Tree column header menu

    Selection Cells

    For multiselection tree tables, the first column contains checkboxes for selecting line items. Besides multiselection, the tree table offers a single-selection mode and also a read-only mode, in which line items are not selectable.

    Tree table – Selection cells
    Tree table – Selection cells

    Select All

    For multiselection tree tables, the column header can contain a checkbox above the selection cells for selecting or deselecting all line items.

    Tree table – Select all
    Tree table – Select all

    Scrollbar

    The tree table allows horizontal and vertical scrolling. You can add any number of line items to the tree table, which uses “lazy loading”.

    To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.TreeTable, property: rowHeight).

    The tree table is optimized to allow faster scrolling within the first 1000 items.

    Tree table – Vertical scrollbar
    Tree table – Vertical scrollbar

    Behavior and Interaction

    Selection

    The tree provides the following possibilities:

    No selection: Items cannot be selected. (property: selectionMode = None)

    Tree table – No selection
    Tree table – No selection

    Single selection: One item in the tree table can be selected. A row selector column is shown. (property: selectionMode = Single)

    Tree table – Single selection
    Tree table – Single selection

    Multiple selection: One or more items can be selected. The tree table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back. The Shift key can be used to select a range.

    For multiple selection, you can choose between two variants.

    • Multi-toggle mode (property: selectionMode = MultiToggle)
    • Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)

    These variants behave differently when the user selects more items than are currently loaded in the front end.

    Multi-toggle

    In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end (keyboard: Ctrl+A). All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

    Multi-selection plug-in

    If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:

    • By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
    • You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
      • The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and a message can appear (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
      • If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets (Keyboard: Ctrl+A).
    • If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.
    Information
    When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

    • The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
    • The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.TreeTable, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

    Tree table – Multiple selection
    Tree table – Multiple selection
    Multi-selection plug-in with a limit
    Multi-selection plug-in with a limit

    Selection Behavior

    An item can be selected in different ways, depending on the configuration of the tree table (sap.ui.table.Table, property: selectionBehavior):

    • Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection tree tables if clicking a row or a cell is not used for anything else.
    • RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
    • RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection tree tables if clicking a row or a cell is not used for another purpose, such as navigation.

    Set the property collapseRecursive to “false” in order to keep the selection on subnodes even after collapsing and expanding the root node.

    Drag and Drop

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

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

    Drag and drop is only available on supporting browsers.

    Drag and drop
    Drag and drop

    Column Header Menu

    Sort

    The column header menu can provide two sort options (sap.ui.table.Column, properties: sortProperty, showSortMenuEntry):

    • Sort Ascending
    • Sort Descending

    The user selects one of these options to sort the corresponding column accordingly (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

    Sort settings in column header menu
    Sort settings in column header menu

    Filter

    The column header menu can provide a search field for entering free text. If the user enters a term in the input field and triggers the search by pressing Enter, the tree is filtered by the tree column and the corresponding value. If no items match the filter values, the filtered tree table may be empty.

    Tree table – Filter
    Tree table – Filter

    Freeze Columns

    The Freeze/Unfreeze option is provided in the column header menu of all columns. Using Freeze on one column freezes all columns from the first one to the selected one.

    Tree table – Freeze
    Tree table – Freeze

    Column Handling

    Show/Hide Columns

    Columns can be shown and hidden. If the tree column is hidden, the following column is the tree column.

    Rearrange Columns

    The user rearranges columns by dragging and dropping the corresponding column header. The tree column is always the first column and cannot be dragged. Keyboard: the focused column header can be moved by one position to the corresponding direction with Ctrl+Left / Ctrl+Right.

    Resize Columns

    Columns are resized as follows:

    • Mouse interaction: The user drags the separator line between two columns (sap.ui.table. Column, property: Resizable). Double-clicking the line optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable). Note that auto-resizing works only if the cells in this column contain one of the following controls: text, label, link, or input.
    • Touch interaction: The user clicks or taps the column header to reveal two buttons: One to show the column header menu, and one for resizing. The user drags the latter to resize the column.
    • Keyboard interaction: The width of the focused column header can be increased with Shift+Right and decreased with Shift+Left.

    Context Menu

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

    When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows (like group headers). Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

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

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

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

    Tree table with context menu
    Tree table with context menu

    Cell Content

    The tree is traditional in that each cell can contain only one data point in one single line.

    Apart from plain read-only text, cells can contain the following:

    While it is technically possible to also use other controls, doing so could lead to issues in regards to alignment, condensed mode, screen reader support, and keyboard support.

    If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false).

    Guidelines

    Filtering

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

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

    Where nodes need to be filtered, keep the following in mind:

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

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

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

    Sorting

    First of all: Is sorting meaningful in your tree? If so, decide on a meaningful default sort order.

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

    Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the tree column.

    To display the current sort state, an icon is shown in the column header of the most recently sorted column. This icon indicates the sort direction (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

    The descending sort order must always be the exact reverse of the ascending sort order. For each column, provide a meaningful sort order. For example:

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

    Loading Data

    To indicate that the table is currently loading items, use the busy state (sap.ui.table.TreeTable, property: busy). Do not show any items or text. As soon as the data has been loaded, remove the busy state and show all items.

    Initital Display

    Think of the initial expand / collapse state of a tree: If your structure contains many items on the root level, it might make sense to collapse the whole tree in the beginning.

    In contrast, if the main items to work with are displayed on a deeper level (e.g. the parent nodes are just some kind of categorization), the tree should be expanded up to the first level where the needed items appear.

    Errors and Warnings

    To indicate that the tree table contains items with errors or warnings, show a message strip above the tree table. On the message strip, provide information on errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

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

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

    Selection

    • We strongly recommend using the multi-selection plug-in. This ensures that all items selected using Select All or as part of a range are included – even if some items were not initially loaded in the front end. This is not the case if you use the multi-toggle option.
    • Do not limit the range selection for the multi-selection plug-in unless you have to.
      • If the dataset is small and/or completely available in the front-end, set the limit property to 0 to enable the Select All option and allow users to select any range.
      • If you have a large dataset, set a limit on the number of selected items to avoid performance issues. Also bear in mind that some actions won’t be helpful if the dataset is too big (for example, a delete operation on 2 million database entries).
    • When setting a limit, also display the corresponding message when the user selects more items at once than the limit allows (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification).
    • For single-selection master-detail scenarios within the flexible column layout, do not show an additional “navigated” indicator.
    • In multiple selection mode, do not show checkboxes in the first data column in the default delivery to avoid confusion.
    • Never disable the selection checkbox. 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.

    Empty Table

    Try to avoid empty tables. If necessary, provide instructions on how to fill the tree table with data.

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

    Add Items

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

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

    Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

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

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

    If your tree doesn’t support adding items to the root, selected node, or selected leaf, disable Create or Add for the corresponding levels.

    Disable Create or Add if more than one item is selected.

    There are three options for adding an item. 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 selected node. Show the Save button on the tree 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 tree tables with up to 8 editable columns. Save the new item at 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, tree tables with more than 8 columns). When the user presses Save in the footer toolbar of the create page, navigate back to the tree table.

    Depending on the flow, an item can be in one of three different states:

    • New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
    • Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the corresponding node. Ignore current sort, filter, and grouping criteria to keep the item visible.
    • Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
      • Inline creation: After Save was triggered on the tree toolbar or at page level.
      • Create with dialog: A tree table showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

    In the context of draft handling new items are not saved at tree table level, but rather with the entire draft.

    For more details, see the guidelines for managing objects (including subarticles).

    Enabling/Disabling Actions

    To indicate if an action can be applied to the current selection:

    • Enable the action if it always works, regardless of whether or not items are selected.
    • Enable the action if it can be applied to all selected items.
    • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Let the user choose whether to apply the action anyway or cancel the action.
    • Only disable the action if it can be applied to none of the selected items.

    For more details, see UI Element – States.

    If the action was applied and the items are still available, keep them selected.

    Message for an action that applies to a part of a selection
    Message for an action that applies to a part of a selection

    Columns

    Minimize the number of columns. Avoid the need to scroll horizontally in the default delivery. In the first column, show the hierarchical data, which should identify the line item. Choose the name over the ID, but if both are needed, show the name first, then the ID.

    The tree table assigns the same width to each column by default. It is recommended that you overwrite this default to provide optimal space for your content (sap.ui.table.Column, property: width).

    If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the browser window size results in a scrollbar. After resizing a column, a scrollbar appears if the width of the table is not enough to show all columns. If the columns use less space than is available, white space appears on the right side of the last column.

    If you define the column width as a percentage, resizing one column affects the width of several or all columns. Text becomes truncated when the browser window size is reduced. This is done to make sure that all columns together fill the space of the table. A scrollbar appears only in case the automatic change of the column widths is not enough to display all columns. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

    If you define the column width as “auto”, the behavior is the same as for “percentage”. In contrast to percentage, “auto” distributes the columns equally.

    To decide on how to set the column width (pixel/rem/em vs. percent/auto), keep the following tips in mind:

    • For tables with only 2 to 3 columns, use pixel-based units. This ensures that on wide screens the values in the columns are not spread over the whole screen, which improves readability of line items.
    • For tables with many columns, where a horizontal scrollbar is usually needed, use pixel-based units. This avoids unintended side effects when resizing columns.
    • For all other tables, use whatever fits your case better.

    Be cautious with mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it could also cause even more unintended side effects when resizing a column. When using percentage-based widths for one or more columns, think of the possibility to not allow end users to resize columns at all.

    Alignment of Cell Content

    Align column headers according to their cell content:

    • Texts are left-aligned.
    • Numbers (except for IDs), dates, and times are right-aligned.
    • Icons are centered.
    • Micro charts are left-aligned.

    In addition, align amounts with currencies to the decimal point. You can do this with the sap.ui.unified.Currency control.

    Note that most currencies have two digits after the decimal point, but there are exceptions, for example:

    • The Tunisian dinar has three digits.
    • The Japanese yen has no digits.

    In tree tables with mixed currencies, all amounts still have to be aligned to the decimal point.

    To enable positive and negative values to be identified more easily, position the minus sign to the right of the number. It is placed in the same position in every row.

    For more information, see currency.

    Formatting Cell Content

    • Note that there are different locale formats, so show dates, times, and numbers in the correct format for the user’s language/country.
    • If you show both a a text and an ID, consider the requirements for sorting, grouping and filtering:
      • If users need to sort, group, and/or filter by both text and ID, show the text and ID in two separate columns.
      • If users only need to sort, group, and/or filter by either text or ID, show the ID in parentheses after the corresponding text.
    • If the unit of measurement is the same for all rows, show the unit of measurement in the column header. Otherwise, show the unit of measurement within the row.
    • If you want to let users sort, filter, or group by amount and by unit of measure independently, put both in different columns. If you combine them in one column, offer only sorting, filtering, and grouping by amount.

    Tree vs. Table

    Trees are more complex than tables due to their hierarchical view. Users tend to have more problems finding items in hierarchical views than in flat lists, except where the hierarchical view is natural. By natural we mean that every child node should be part of only one parent, and this relationship between the child and parent is clear and well known.

    Do
    Example of an acceptable use of tree tables
    Example of an acceptable use of tree tables
    Do
    A clear parent-child relationship
    A clear parent-child relationship

    When you use trees, you should choose broad hierarchies over deep hierarchies. Deep hierarchies make finding items more complicated. So try to reduce hierarchical levels where possible, especially if the hierarchy is not natural. Ideally, a tree should have a maximum of four levels, the first two of which should contain the most important items.

    Don't
    Avoid unnecessary depth in the hierarchy
    Avoid unnecessary depth in the hierarchy
    Do
    Favor breadth over depth in the hierarchy
    Favor breadth over depth in the hierarchy

    You can use the following methods to reduce hierarchy levels:

    • Avoid single root nodes. A single root node is often used to provide a Select All feature. Since the tree control provides an extra space for a Select All feature, the root node is not usually needed.
    • When you use only two levels, choose a grouped table or grouped ALV over a tree table control. Expand all groups for the default delivery.
    • Container nodes at the top level can usually be replaced by tabs or value pickers.
    • Eliminate unnecessary mid-level containers, for example, by combining redundant ones.
    • Exercise care when using a tree due to its overall complexity. The hierarchical structure of the data does not necessarily mean that a tree control is required.

    Design Concepts

    The tree table can be used to display large amounts of hierarchical data. Unfortunately, tree tables have a high data density and therefore convey an immediate feeling of complexity. Ideally, tree tables with large amounts of data should only be shown if there is no other option. You should instead try the following:

    • Flatten the data. A list, table, or ALV is still complex, but less so than a tree table.
    • Break down the data into manageable chunks. Allow the user to navigate or drill down between them.
    • Use charts with drilldown functionality until the amount of data is more manageable.

    Try to avoid horizontal scrolling in the default delivery.

    Navigation

    To trigger navigation on line item level, choose one of the following options:

    • Use a link for the attribute that identifies the row. Clicking the link triggers the navigation. This is the preferred option.
    • Add the RowActions column and show the navigation arrow (  ) at the end of the row. No column header text is required. The navigation column is fixed and will not scroll away. Users also cannot personalize this column. The navigation arrow triggers the navigation.
      Do not use the RowActions column for actions other than navigation and deletion.

    Special case: Multi-selection in a master-detail scenario
    When a multi-selection table is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case, you can display a “navigated” indicator to show which item is currently open.

    Examples of Incorrect and Correct Usage

    When you use trees:

    • Choose breadth over depth.
    • Emphasize important values. Do not let the user run into a wall of text without guidance. You can use bold text for this.
    • Try to minimize the number of columns, especially if there is a large number of rows.
    • Optimize column width for its initial visible content. Do not automatically adjust column width based on content changes.
    • Do not wrap content, truncate it. End users can easily change the column width to see the full text.
    Don't
    Avoid truncating the initial visible content in the default delivery
    Avoid truncating the initial visible content in the default delivery
    Don't
    Never wrap texts
    Never wrap texts
    • Maintain a fixed layout, except when the user wants to change it.
    • In the default layout, use the tree column for the item name or data that identifies the row. This helps the user to choose between different items.
    • Create a clear and immediately understandable hierarchy. Use clear parent-child relationships. If this is not possible, add a child in different nodes to help the user find the element.
    Do
    Acceptable: repeat entries to optimize finding items
    Acceptable: repeat entries to optimize finding items
    • Consider persisting the layout settings. When a user reopens the app, show the tree table with the same column sizes, column order, and view settings as last defined by this user.
    • Use the Select All feature only if it makes sense. Note that selecting a lot of data also takes time and might not be appropriate for all use cases. For example, a delete operation on two million database entries might not be very helpful in many cases.
    • Set the property collapseRecursive to “false” in order to keep the selection on subnodes even after collapsing and expanding the root node.

    Empty Tree Tables

    Avoid empty tree tables. If necessary, provide instructions on how to fill the tree table with data (sap.ui.table.TreeTable, properties: noDataText, showNoData).

    Examples:

    • If a tree table is initially empty, provide at least a basic text:
      No items available.
      Overwrite this whenever a hint can be provided on how to fill the tree table with data.
    • If a tree table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
      No filters set. To start, enter your search and filter settings and run the search.
    • If a tree table is used together with a filter bar and the filter does not return results, use the following text:
      No items found. Check the search and filter settings.

    Adapt the texts above if:

    • The standard text is not precise enough for your use case (for example, no search is offered, only the search is offered).
    • You are using the live search (no Go button in the filter bar). In this case, leave out “run the search”.
    • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).

    Highlight Items

    To show that an item needs attention, a highlight indicator can be shown in front of the item. The highlight indicator can be used to indicate:

    • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
    • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
    • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

    Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

    For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

    (sap.ui.table.TreeTable, aggregation: rowSettingsTemplate)

    Highlighted items
    Highlighted items

    Drag and Drop

    Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, 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. These are keyboard operable and available on all browsers.

    Use drag and drop only in addition to existing visible UI elements
    Use drag and drop only in addition to existing visible UI elements

    If you offer drag and drop for rearranging items within a tree table, use the following options:

    • For dropping items as a child, use whole nodes as drop targets (sap.ui.core.dnd.DropPosition.On).
    • For dropping items on the same level, use the space between items as drop targets (sap.ui.core.dnd.DropPosition.Between).
    • If you want to allow users to drop items as a child or sibling, offer both drop targets (sap.ui.core.dnd.DropPosition.OnOrBetween).

    This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

    Drop target on an item
    Drop target on an item

    Do not combine rearranging items within one level and sorting. If you really need to do so, make sure there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

    Moving items from one node to another can be combined with sorting without any issues.

    Don't
    Do not combine rearranging items on the same level with sorting
    Do not combine rearranging items on the same level with sorting

    Visible Alternatives to Drag and Drop

    Depending on the functionality you need, use one or more of the following alternatives:

    • To move items up or down within a node:
      Use the  Move Up and  Move Down buttons on the toolbar. These buttons move the selected items until the first selected item can’t be moved up / the last selected item can’t be moved down any further.
      Depending on your tree, this can make sense for both leaves and nodes, only for leaves, or only for nodes. When moving a node, move the whole node and (if applicable) all its children up or down to the next position within the parent node.
      Always make sure that when the user moves an item in one direction and then moves it back, the order is the same as it was before.
      Do not combine the option to move items up and down with sorting.
    • To move items to another node:
      Use Copy and Paste buttons on the toolbar.
      Alternatively, offer a Move To button. Clicking Move To opens a dialog that shows all the nodes of the tree, but no leaves. Selecting an item in this dialog closes the dialog and moves the corresponding items to the selected node.
    • To change the level of an item:
      In some trees, such as document structures, users can change the level of an item without affecting the level of parent or child items. In this case, use left and right arrow buttons (   ).

    Context Menu

    Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar). Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

    The context menu can be triggered for the table, row, or cell. However, we do not recommend using context menus for cells: because the content of a cell is a different touch target than the cell itself, opening a cell context menu via touch is quite hard, even in cozy mode.

    Do not combine context menus with condensed mode: editable controls fill the entire space inside a cell. Because of this, context menus cannot be opened at all with touch or mouse interaction.

    Tables in Object Pages

    In the object page, we advise against using analytical, grid, and tree tables. Instead, use a responsive table and offer navigation to a list report with the table types mentioned above.

    For more information on the use of tables within the object page, see the Tables section of the Object Page article.

    Export to Spreadsheet

    On the table toolbar, apps can provide a menu button for exporting table data to a spreadsheet. For the export, use the export to spreadsheet function.

    'Export to Spreadsheet' menu button
    'Export to Spreadsheet' menu button

    Resources

    Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

    Elements and Controls

    Implementation

    Form / Simple Form

    Information
    This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

    For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

    Intro

    A form is used to present data to the user and to allow users to enter data in a structured way.

    The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

    In SAPUI5, forms can be built using two different controls:

    With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

    The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

    • The layout and structure are defined by the content that is entered.
    • Form containers and form elements are created automatically according to the content type.
    • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
    • All other controls following this label will be assigned to its row (form element).

    Types

    There are three types of forms:

    • Display-only: the data is presented only as label-value field pairs without editable fields.
    • Editable: the data is presented as label-input field pairs, so users can enter data.
    • Mixed: some fields are editable and some are not.
    Form control in display- only mode
    Form control in display- only mode
    Form in edit mode
    Form in edit mode
    Developer Hint
    The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
    Information
    Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

    Responsiveness

    The default settings of the control are not ideal for all possible use cases. Instead, applications can use one of the various layouts for the S, M, L and XL sizes.

    Column Layout

    The ColumnLayout control renders a form group in a column-based responsive way. Depending on its size, the group is divided into one or more columns.

    • XL – max. 6 columns
    • L – max. 3 columns
    • M – max. 2 columns
    • S – 1 column

    For size XL, we recommend using the full 6 columns for large forms with a lot of content. This gives you greater flexibility when organizing the content and the form groups.​

    To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns. The group elements are spread out into columns, depending on the number of group elements and their size.

    Example:

    • 4 columns and 2 groups: each group will use 2 columns.
    • 3 columns and 2 groups: the larger one will use 2 columns, the smaller one 1 column.

    The size of a group element will be determined by the number of visible elements assigned to it. If there are more groups than columns, every group uses only one column. So the last row of the form control will not be fully used. This will result in white space.

    The form elements are spread out to the columns of a group arranged in a newspaper-like order. The position of the labels and fields depends on the size of the used column. If there is enough space, the labels are next to the fields, otherwise above the fields.

    If you use the default form settings, each form group is displayed in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right side of the screen.

     

    The examples show how forms with one and two form groups are displayed with and without layout balancing.

    One form group with default arrangement
    One form group with default arrangement
    One form group with balanced column layout
    One form group with balanced column layout
    Two form groups with default arrangement
    Two form groups with default arrangement
    Two form groups with balanced column layout
    Two form groups with balanced column layout

    Responsive Grid Layout

    The responsive grid layout is a form using a responsive grid. Depending on the available space, the groups are rendered in one or multiple columns, and the labels are rendered in the same row as the fields or above the fields. This behavior can be influenced by the properties of this layout control.

    By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

    Note: For downward compatibility reasons, the default form layout control for the form and simple form is the column layout, not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

    Breakpoints

    Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

    Form with breakpointM – Size S
    Form with breakpointM – Size S
    Form with breakpointM – Size M
    Form with breakpointM – Size M

    The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

    Form with breakpointL – Size M
    Form with breakpointL – Size M
    Form with breakpointL – Size L
    Form with breakpointL – Size L

    Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

    Form with breakpointXL – Size L
    Form with breakpointXL – Size L
    Form with breakpointXL – Size XL
    Form with breakpointXL – Size XL

    In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

    Padding of a container
    Padding of a container
    Developer Hint
    To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

    Label-Field Ratio

    For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

    The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

    We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

    Form with a label-field ratio of 3:5:4
    Form with a label-field ratio of 3:5:4
    Developer Hint
    To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

    Otherwise..

    • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
    • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
    • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

    Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

    Size S (Smartphones and Dialogs)

    The form and simple form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

    The label-field ratio is 12:12:0 by default:

    • 12 grid columns of the responsive grid layout are used by the labels.
      (A label handles the space of a whole row.)
    • 12 grid columns of the responsive grid layout are used by the fields.
      (A field handles the space of a whole row.)
    • 0 grid columns of the responsive grid layout are used by empty columns.
      (There is no empty space on the right of the field.)
    Form in size S
    Form in size S

    Size M

    Size M of the form and simple form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

    The label-field ratio is 2:10:0 by default:

    • 2 grid columns of the responsive grid layout are used by the labels.
    • 10 grid columns of the responsive grid layout are used by the fields.
    • 0 columns of the responsive grid layout are used by empty columns.

    Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

    Form in size M
    Form in size M

    Size L

    The form and simple form in size L use a two-column layout within the responsive grid layout by default. That means that the form groups are placed next to each other to have all the information on one screen and to avoid scrolling. In these columns, the labels are positioned in the same row as the corresponding input field or value. So the form groups adopt the Z layout (reading direction in rows, not in columns).

    The label-field ratio is 4:8:0 by default:

    • 4 grid columns of the responsive grid layout are used by the labels.
    • 8 grid columns of the responsive grid layout are used by fields.
    • 0 grid columns of the responsive grid layout are used by empty columns.
    Form in size L
    Form in size L

    Size XL

    Like the form and the simple form in size L, the size XL uses also a two-column layout within the responsive grid layout by default. To have all the information on one screen and avoid scrolling, the form groups are placed next to each other.  In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

    The label-field ratio for size XL is 4:8:0 (technically the value is set to -1 and inherits the value of size L, see also the development hint below) by default:

    • 4 grid columns of the responsive grid layout are used by labels.
    • 8 grid columns of the responsive grid layout are used by fields.
    • 0 grid columns of the responsive grid layout are used by empty columns.
    Form in size XL
    Form in size XL
    Developer Hint
    For forms and simple forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

    Layout

    One Page, One Form

    If a form contains only one group, do not use a group title – instead, use the form title.

    Form with only one group (form title)
    Form with only one group (form title)

    If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

    Form with several groups (no form title)
    Form with several groups (no form title)

    If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

    A form as one of several elements on a page (form title)
    A form as one of several elements on a page (form title)

    One Page, Many Forms

    If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

    Several forms on a page (emphasized groups)
    Several forms on a page (emphasized groups)
    Forms with several groups
    Forms with several groups

    Various Layouts

    The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

    Size S (Smartphones and Dialogs)

    Retain the default behavior (single column layout with a label-field ratio 12:12:0).

    Form in size S (12:12:0)
    Form in size S (12:12:0)

    Size M (Tablet) – Full Screen

    If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

    Form in a split screen – Size M (4:7:1)
    Form in a split screen – Size M (4:7:1)

    If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

    Form in full screen – Size M (3:5:4)
    Form in full screen – Size M (3:5:4)

    As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

    Form with long labels and fields – Size M (4:8:0)
    Form with long labels and fields – Size M (4:8:0)

    If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

    Form with several form groups (two columns) – Size M (12:12:0)
    Form with several form groups (two columns) – Size M (12:12:0)
    Developer Hint
    Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

    Size L (Desktop Screens)

    If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

    Form with a single form group (one column) – Size L (3:5:4)
    Form with a single form group (one column) – Size L (3:5:4)

    If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

    Form with several form groups (two columns) – Size L (12:12:0)
    Form with several form groups (two columns) – Size L (12:12:0)
    Developer Hint
    Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

    Size XL (Desktop Wide Screens)

    If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

    Form with a single form group (one column) – Size XL (3:5:4)
    Form with a single form group (one column) – Size XL (3:5:4)

    The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

    Form with an empty column – Size XL (4:8:0)
    Form with an empty column – Size XL (4:8:0)

    If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

    Form with single group in a column layout - Size XL - (12:12:0)
    Form with single group in a column layout - Size XL - (12:12:0)

    If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

    Form with multiple form groups (two columns) – Size XL (4:8:0)
    Form with multiple form groups (two columns) – Size XL (4:8:0)

    If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

    Form with two form groups (three columns) – Size XL (12:12:0)
    Form with two form groups (three columns) – Size XL (12:12:0)
    Form with three form groups (three columns) – Size XL (12:12:0)
    Form with three form groups (three columns) – Size XL (12:12:0)

    If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

    Form with a lot of white space (two columns)
    Form with a lot of white space (two columns)
    Form with less white space (single-column layout)
    Form with less white space (single-column layout)
    Developer Hint
    Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

    Components

    The following UI elements can be placed in the form container:

    Guidelines

    • Order the form logically from a user’s perspective. For example, ask for a user’s name before asking them for their address.
    • Group related information by using form and group titles.
    • Use Column layout instead of Responsive Grid layout, if possible.
    • Try to arrange form groups (especially in size L and XL) in a way that the form:
      • Is easy to read and understand.
      • Does not contain too much white space (split groups if necessary).
    • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
    • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
    • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

    Label

    To avoid truncation, labels within forms wrap automatically.

    Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is to make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

    • A label is not a help text. Give each field a meaningful label. Make labels succinct, short and descriptive.
    • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property, and the asterisk will be inserted automatically.
    • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the style sheet. Do not write the colon manually in the label text.
    • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)

    Label Alignment

    • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
    • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
    Information
    The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

    Empty State Indicator

    If the form field doesn’t have a value, show an empty state indicator in display mode. This helps the user to better scan the form and perceive the field label and empty content as one unit.

    Developer Hint
    The empty indicator does not show by default. You need to activate it for the respective text (property: emptyIndicatorMode).
    Empty state indicator
    Empty state indicator

    Unit of Measurement

    You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

    If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

    Unit of measurement
    Unit of measurement

    Amount Alignment

    When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

    When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

    Data Loss Message

    Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

    Form Field Validation

    Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

    Field validation and validation report
    Field validation and validation report

    Input Assistance

    Intelligent systems can help users by recommending appropriate content or suggesting an action or input the user may “prefer”. The system assists the user by entering data or filtering data. Typical examples might be a search phrase suggestion, an appropriate form template, or a set of suggested default values for certain fields, based on the user input and interaction history.

    For more information, see Designing Intelligent Systems – Input Assistance.

    Error Prevention

    Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

    Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

    Placeholder

    Provide a placeholder (or input prompt) as a short hint (a word or short phrase) to help the user with data entry. A hint can be a sample value or a brief description of the expected format.

    Avoid using the placeholder attribute as an alternative to a label. This is important because the placeholder text is overwritten as soon as the form is filled out. Labels are necessary to indicate the meaning of the form fields when the placeholders are no longer visible.

    Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

    Toolbar

    The form supports actions on form toolbar level as well as on group header level. Application development teams can add actions such as ‘Edit’, ‘Save’ or ‘Cancel’. If there is an action that only applies to the specific group on group level, it can only be added on the group header level of the specific group.

    Expanded/ Collapsed Form

    The form supports expand / collapse buttons on a per-group level. However, we recommend avoiding the usage of expand / collapse behavior on a form.

    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

    Scroll Container

    The scroll container is an empty area that can be filled with content, such as other UI elements. The user can scroll through the content.

    When to Use

    Use a scroll container if:

    • You want to provide a content area that would otherwise be partly or completely covered or hidden.

    Do not use a scroll container if:

    • A page uses a full screen element that can handle vertical scrolling.
    • You are using other controls that come with their own scroll container, such as a dialog, timeline, or panel.
    • You plan to nest different scroll containers that scroll in the same direction.
    • You plan to have several scroll containers with different scroll directions (horizontally and vertically) on one page. This may lead to confusion about when to use which scrolling direction and how it all fits together.

    Behavior and Interaction

    The scroll container displays a scrollbar on the side for vertical scrolling and on the bottom for horizontal scrolling.

    In addition, the scroll container is also focusable.

    Vertical scrolling in a list
    Vertical scrolling in a list

    Responsiveness

    The scroll container is responsive and adapts to the screen size. By default, the width consumes the complete available width and the height reflects the height of the content. You can also set a fixed width or height. Always use responsive controls for the content, so that they also adapt to the available width and height.

    Guidelines
    If you are only using horizontal scrolling, do not set the height, or ensure that the height of the container always exceeds the height of the content.

    Related Links

    Elements and Controls

    Implementation

    Invisible Message

    The invisible message control provides a hidden message that can be used by assistive technologies, such as screen readers. Invisible messages provide information to users when the visible screen content changes dynamically (for example, when a page is refreshed).

    When to Use

    Use the invisible message if:

    • You need to offer accessibility support to communicate dynamic changes on the interface that are visually perceptible.
    • You need to provide a message for screen reader users independently of the focus position.

    Do not use the invisible message if:

    • You want to provide static and visible, but non-focusable information for users of assistive technologies. Use the invisible text instead.
    • You want to provide additional information for users of assistive technologies that is not available for sighted users. While you should not discriminate users of assistive technologies, you should also not give them “privileges” .
    • You want to hide information. It might still be available for users of assistive technologies.
    • You want to hide long texts. The information is probably important enough to be shown! Furthermore, short texts are far more convenient, even for users of assistive technologies.

    Examples

    The examples below show typical use cases for invisible messages.

    Information
    Invisible messages may also be provided by the framework as an intrinsic part of the control. If no message is provided out of the box, you must create one.

    Search

    • Indicate when a results list is rendered following a search.
    • Indicate the number of hits found.
    • Provide a short hint on how to get to the result list.

    Navigation within Dialogs

    Indicate when the entire content of a dialog changes. Provide accessibility support for navigation in a dialog.

    Dialog navigation - List
    Dialog navigation - List
    Dialog navigation - Details
    Dialog navigation - Details

    Saving

    Indicate when the page or a form has been saved in apps with or without draft handling.

    'Draft saved' indicator
    'Draft saved' indicator

    Auto-Update

    Use an invisible message to indicate:

    • When a page has been refreshed
    • When data on the page has been updated automatically
    • When an entry in an input field has been corrected automatically

    Deletion

    Provide a success message when an item has been deleted. Refer to the UI text guidelines for message toasts.

    Dynamic Messaging

    Indicate when a message strip has appeared automatically and provide its content.

    Information message strip
    Information message strip

    Dynamic Change in a Control

    Indicate when a user action has changed the appearance of a control (for example, if pressing a button changes the button text or icon tooltip).

    Toggle button with label change
    Toggle button with label change

    Top Tips

    • Provide short and meaningful texts.
    • Avoid mentioning system or configuration details.

    Related Links

    Elements and Controls

    Implementation

    PDF Viewer

    The PDF viewer control displays PDF documents within your app. It can be embedded in your page layout, or you can set it to open in a popup dialog. In addition, this control allows you to print and download the PDF documents it displays.

    Usage

    Use the PDF viewer control if:

    • You want your app to display PDF files on all devices and platforms.
    • You want the users of your app to be able to preview their documents as PDF files right inside your app.
    • You need to ensure the consistent behavior of PDF files across all SAP Fiori apps.
    • You need to work with events (loaded, validation, error) provided by the PDF viewer.

    Do not use the PDF viewer if:

    • You need to provide an interactive PDF file (such as a data input form).

    Responsiveness

    The PDF viewer control is fully responsive on large-screen devices (size L). The range of responsive behavior available on desktop devices depends on the display mode.

    • When the PDF viewer opens in a dialog popup:
      By default, the dialog supports two or more actions, such as Close and Download. On large-screen (desktop) devices, the action buttons are right-aligned. Use compact mode to ensure optimal padding and margins on desktop devices.
      If the content height is increased beyond the screen height, the dialog height cannot go beyond 4 rem from the top and bottom of the screen.
      The dialog popup must be resized automatically and cannot support dragging or custom resizing.

     

    • When the PDF viewer is embedded in a container on the app page:
      The dimensions of the frame in which the PDF file is displayed are defined by the PDF viewer properties.
      The control in which the PDF viewer is embedded must have at least 1 rem (16 px) padding to set it apart from the rest of the content.
      Only vertical scrolling is allowed. The behavior of desktop touch devices should follow the default behavior of the device or platform.

    On mobile devices (smartphones and tablets), the PDF viewer control renders a toolbar with the title and a download icon, which behaves as a standard device/browser file link.

    If required, you can customize the behavior for mobile devices and trigger the default device action for the file link from a different anchor in the application.

    Size L - Popup mode
    Size L - Popup mode
    Size L - Embedded mode
    Size L - Embedded mode
    Size M - Tablet
    Size M - Tablet
    Size S - Mobile
    Size S - Mobile

    Layout

    Displaying PDF Files in a Dialog

    The dialog is positioned in the center of the screen. It opens in a modal window to attract the user’s attention when it displays emergency states. The dialog consists of:

    • A dialog header
    • A dialog PDF content
    • A dialog footer

    Displaying Embedded PDF Files

    The secondary mode of the PDF viewer displays PDF files directly on the page. The application owner, using the PDF viewer control, provides the dimensions of the frame in which the PDF file is embedded. The container should have at least 1 rem (16px) padding from the other content on the page to allow users to distinguish between the embedded PDF and the rest of the page’s content.

    When the PDF viewer is embedded on the page, it comprises:

    • An overflow toolbar header
    • A container for rendering the PDF file (determined by the application owner)
    Schematic visualization of popup mode
    Schematic visualization of popup mode
    Schematic visualization of embedded mode
    Schematic visualization of embedded mode
    Developer Hint
    The footer can be extended by any desired buttons. However, both the Close and Download buttons must be displayed. This is to ensure that the accessibility requirements are fulfilled. Additional information about action placement and order can be found in the Action Placement article.

    Components

    The PDF viewer in popup mode is rendered within a Dialog and consists of:

    Title(Header): The title text appears in the dialog header.

    Content: This area contains the actual PDF file displayed within the content of the dialog.

    Footer with actions: The footer contains two mandatory buttons: Close and Download. Other actions can be added to the footer as well.

     

    The PDF viewer in embedded mode can be rendered in any container desired by the application.

    The title is displayed within the Toolbar (Overflow Toolbar).

    Developer Hint
    Use a Flexbox container to wrap the embedded mode of the PDF viewer inside the application.

    Behavior and Interaction

    All the interactions for the PDF files themselves must remain the same across platforms and browsers: paging, scrolling, zooming, and print must all be available.

    Download – For accessibility reasons, the PDF viewer always provides an additional download button for downloading the displayed PDF file and gives users the option to download the embedded PDF renderer on a specific device or system (not all PDF reader plugins have their own download button).

    Popup mode interactions:

    • No custom resizing of the dialog
    • No dragging of the dialog

    Guidelines

    To avoid the risk of performance issues, do not embed more than three instances of the PDF viewer per page. You may embed more instances of the PDF viewer in one page if the number of PDFs does not affect performance. Carry out benchmark tests to ensure that performance will not be affected.

    The PDF viewer can be used within other sap.m components, such as carousel and panel, respecting the specific guidelines of these components.

    The embedded mode of the PDF viewer can be used on the Object Page if the container is as wide as the object page. If this is not the case, use the popup mode of the PDF viewer instead.

    The PDF viewer can provide accessibility options when used with screen readers and other accessibility software. To ensure that all the accessibility options are supported, you need to have Adobe PDF Reader installed.

    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

    T Account

    In double-entry bookkeeping, journal entries are transferred to the general ledger by posting their debit and credit amounts on specific ledger accounts, which are often referred to as T accounts. A ledger account (or T account) is usually displayed in a format that resembles the letter T: with the account name above the T, debit entries to the left of the T, and credit entries to the right of the T.

    T accounts are usually clustered together, so the accountants can analyze how individual line items from different journal entries affect the ledger balances.

    Example of a T account
    Example of a T account

    Usage

    Use the T account if:

    • You need to analyze how individual line items affect one or several ledger accounts.
    • You want to highlight the cross-account impact of one journal entry.
    • You want to aggregate data of individual ledger accounts and provide total balances.

    Do not use the T account if:

    • You need to aggregate data through a different dimension than the account balance. Use a table instead.
    • You need to display objects that are not journal entry line items.

    Responsiveness

    The T account control is fully responsive, and uses 100% of the available width of the container in which it is embedded. Depending on the available width, the number of T accounts on each line is updated dynamically to fit the available space.

    On mobile devices, the T account control requires the full available width in order to display all its content.

    The minimum width of each T account element is 20 rem (320 px). The width of the T account element grows until it reaches a breakpoint where enough width is available to render 2 or more T accounts on one line, leaving a space of 1 rem (16 px) between the T account items.

    Size S
    Size S
    Size M
    Size M
    Size L
    Size L

    Layout

    The T account control consists of a header toolbar, an account group heading, and individual T account elements. The header toolbar and account group heading can be hidden on the API level.

    Schematic visualization of a T account
    Schematic visualization of a T account

    Components

    By default, the T account control consists of a header toolbar, account group heading, and T accounts.

    Header Toolbar

    • A – Title: Provides a short and meaningful summary of the control’s content.
    • B – Total Balance: Calculates the overall balance based on total credit and debit amounts of the ledger accounts included.
    • C – View Switch: Switches the view between the T account view and table view.
    • D – Settings: Displays a settings dialog, allowing users to show or hide additional information about accounts.

    Account Group Heading

    Each account group heading uses the expand/collapse behavior of the sap.m.Panel control, with an additional total balance indicator for the T accounts in the group as well as Expand All / Collapse All buttons. The Expand All / Collapse All buttons can be used to expand or collapse the content of all T accounts included in this account group.

    • A – Expand/Collapse: Expands or collapses the group of accounts.
    • B – Account Group Title: The name of the group of accounts.
    • C – Group Balance: Calculates the balance based on total credit and debit entries of all T accounts included in the account group.
    • D – Expand All: Expands all T accounts within the group of accounts.
    • E – Collapse All: Collapses all T accounts within the group of accounts.

    T Account

    Every T account element consists of a heading, debit and credit content headings, and individual ledger entry blocks.

    The number of individual entry blocks is unlimited and could potentially reach hundreds of blocks.

    The entry blocks are nested under Credit and Debit headings. Each entry block takes 50% of the available width of the container. The credit and debit entry blocks are separated by a 1 rem (16 px) space.

    • A – Expand/Collapse: Expands or collapses the T account.
    • B – Account Title: The name of the T account.
    • C – Account Balance: The sum of all credit and debit entries in the T account.
    • D – Debit Content Heading
    • E – Credit Content Heading
    • F – Entry Block Amount: Provides the amount for a single ledger entry.
    • G – Entry Block: Displays details of a specific ledger entry.
    Header toolbar
    Header toolbar
    Account group heading
    Account group heading
    T account
    T account

    Behavior and Interaction

    Matching Entries

    Each journal entry usually impacts several ledger accounts. When the user clicks an entry in a T account, the control highlights this entry and all related entries in other T accounts, which helps identify matching entries in different accounts.

    Highlighting for related entries
    Highlighting for related entries

    Color Indicators

    You can allow users to add color indicators to specific journal entries.

    The T account control supports this on API level. However, the implementation should be done on the app level.

    Information
    To ensure consistency with other controls, sap.m.ColorPalette or sap.ui.unified.ColorPicker controls must be used together with standard SAP Fiori color palettes.
    Tagging
    Tagging

    Drag and Drop

    By default, the control arranges T accounts dynamically to consume as little space as possible within the column grid. However, users can rearrange the T accounts freely by dragging them around.

    If you would like to let users store their reordered layouts, use the variant management control.

    View Settings

    The view settings dialog enables the users to show or hide certain attributes of each entry block in a T account.

    Additionally, you can show or hide labels that precede the values.

    View settings
    View settings

    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

    Network Graph

    The network graph displays a large amount of data by highlighting the relationships between individual records. Records are displayed as nodes, and connectors (lines) show the relationships between them. The vivid display of network nodes can highlight non-trivial data discrepancies that would have been previously overlooked.

    Sample implementation of a network graph
    Sample implementation of a network graph

    Usage

    Use the network graph if:

    • You need to display a large amount of data and contextual information. Use cases include material management and supply chains, logistics structures, and value chains.
    • You want to display complex nonlinear structures, trees, and generic charts (such as organizational charts).
    • You want to give the data a spatial context.

    Do not use the network graph if:

    • You want to visualize a document flow. Use the Process Flow control instead.
    • You want to enable editing of displayed data. Note that the network graph is available in read-only display mode.
    • You need to embed the chart into smaller areas or use it as embedded analytics.

    Responsiveness

    The network graph is not a responsive control. Only the top bar and popovers are fully responsive. The graph content, including all the groups, nodes and connectors, keeps the same proportions regardless of the screen size. The proportions are changed only with zoom.

    Size S
    Size S
    Size M
    Size M
    Size L
    Size L

    Layout

    The network graph is split into a header toolbar that contains all the controls, and the chart.

    As an extension to this layout, the control can provide a separate column either on the right or left side of the graph. This column contains a chart map to enable users to navigate to a very large structure more easily. The map displays a smaller version of the graph and the corresponding active area. This column can also be extended by other SAP Fiori controls in order to provide users with enhanced application capabilities.

    Schematic visualization of a network graph
    Schematic visualization of a network graph
    Extension panel on the right
    Extension panel on the right
    Extension panel on the left
    Extension panel on the left

    Types

    The network graph comes with three different layout algorithms:

    • Generic unordered KLay layout
    • Column-based layout displayed as either vertical or horizontal swim lanes
    • Force layout

    Each of the layouts can be visualized as a directed or undirected chart. A bi-directional mode is also supported.

    Undirected: Data dependency (parent-child) or data flow is not implemented.

    Directed: Data dependency is implemented, and different chart orientation can be set. By default, the network graph is oriented left-to-right. Other chart orientations include top-down, center-out, or right-to-left.

    Generic unordered KLay
    Generic unordered KLay
    Column-based layout - Vertical
    Column-based layout - Vertical
    Column-based layout - Horizontal
    Column-based layout - Horizontal
    Force layout
    Force layout

    Components

    By default, the network graph is split into the header toolbar area and the graph content. Within the graph content, groups, nodes, and connectors are displayed. All of these elements are interactive and display action menus or popovers with additional information.

    Header Toolbar

    • A – Title: Provides a short, meaningful summary of the chart contents.
    • B – Search Field: Standard search component with variant suggestions enabled by default.
    • C – Legend: Toggles the legend on/off.
    • D – Zoom In: Zoom in with both mouse wheel or by clicking the icon.
    • E – Current Zoom Level: Zoom level is expressed as a percentage of the original current chart size.
    • F – Zoom Out: Zoom out with both mouse wheel or clicking the icon.
    • G – Fit to Viewport: The network graph automatically applies a zoom level to fit the whole chart into your viewport.
    • I – Fullscreen: Toggles the full-screen view.

    Chart Area

     

    Node

    A node represents a single record in the underlying dataset comprising multiple field values. You can use two different shapes to represent a node: a rounded rectangle or a circle.

    You click a node to select it. A menu is then displayed, which enables you to expand or collapse the connecting chart structure, display a details popover, or a links popover.

    Connector

    A connector represents the relationship between two records and can be displayed as a straight line or a line with arrows.

    You click a connector or the surrounding area to call up the details popover for that specific connector.

    Group

    A group is a chart element that represents a collection of nodes. A group is envisioned as a slightly larger box containing 1-n nodes. When a group is collapsed it behaves like a node.

    Overview of groups
    Overview of groups
    Network graph toolbar
    Network graph toolbar
    Overview of nodes
    Overview of nodes
    Overview of connectors
    Overview of connectors
    Warning
    Following features have not yet been integrated into this version and will come in the next release(s):

    • Icons for rounded rectangular nodes
    • Semantically colored values with different font-weight
    • New visuals for Group statuses
    • Starting Node visualization

    Behavior and Interaction

    Navigation and Zoom

    A user can navigate around the entire network graph by holding down the left mouse button and dragging the mouse. By dragging the graph, the user changes the active area of the available graph map extension. Clicking or dragging the selected area in the graph map extension changes the focus area of the network graph.

    To zoom in or out, the user can use the mouse wheel, pinch open or pinch close on the touch devices, or click the respective buttons on the top bar. Each of these actions changes the number label, located between the zoom in and zoom out icon buttons, and indicates the current zoom level.

    Fit to Viewport automatically adjusts the zoom level to fit the entire network graph into the user’s viewport.

    Component Interaction

    Clicking a node displays a menu, which provides the users with the option to collapse the following chart structure, display the details popover, or display the links popover.

    Clicking a connector or the area surrounding it calls up the connector’s details popover.

    For group interactions, clicking the display details icon button nested in the group heading calls up the group’s details popover (it also contains the list of the nodes included in the group).

    Collapsed Structure Indication

    In more complex structures, many structures may be hidden within the graph. To indicate collapsed structures, we use a visual indication to represent collapsed structures following the node and collapsed structures within a group.

    Partially Expanded Indication

    In a directed graph, Expand/Collapse applies only to the subtree directly connected to the selected node. Each node supports a three-state action button for expanding or collapsing:

    • Fully expanded
    • Partially expanded
    • Collapsed

    When a user clicks the action button in a fully expanded state, the affected node’s subtree is collapsed, and the action button of that node is indicated as collapsed. All other nodes sharing parts of the subtree with this node and will then be indicated as partially expanded.

    When a user clicks the action button in a partially expanded state, the affected node’s subtree is collapsed, and the action button of that node is indicated as collapsed. All other nodes affected by this action are indicated as partially expanded.

    When a user clicks the action button in a collapsed state, the affected node’s subtree is expanded and the action button of that node is indicated as expanded.

    Node interaction showing 'More' menu and 'Details' popover
    Node interaction showing 'More' menu and 'Details' popover
    Visual indication of collapsed structure following the node or group
    Visual indication of collapsed structure following the node or group
    Indication of collapsed, expanded, and partially expanded structures
    Indication of collapsed, expanded, and partially expanded structures

    Styles

    Each node can be visualized with a circle or rounded rectangle shape. These two shapes can be combined inside one graph to provide users with deeper semantic meanings: for example, circular nodes represent customers, whereas rounded rectangles represent suppliers.

    Semantic meanings can be assigned to line styles for connectors, and semantic colors can be assigned to both nodes and connectors.

    Node Types

    As mentioned above, there are two default node shapes: circle or rounded rectangle. In addition, these node shapes have different label and title (icon) positioning.

    If needed, the application owner can also define the number of the allowed lines for a node title.

    Connector Types

    You can give connectors semantic meaning by assigning them semantic colors or different line types. You can also use both semantic colors and different line types to provide connectors with a deeper meaning.

    Connector types and their semantics
    Connector types and their semantics

    Guidelines

    In applications, embed the network graph only within components that use the whole canvas area, such as the tab container on the object page. Do not embed the network graph in smaller containers, such as panels, headers, tables, forms, and dialogs.

    The network graph is not a substitute for a Process Flow. For more details, see the Usage section at the top of this article.

    Keep the amount of information inside each node to a minimum. You can reveal more information via the details popover.

    Resources

    Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

    Elements and Controls

    Implementation

    Tree

    Within SAP Fiori, we distinguish between tree tables and trees. Both usually allow the user to display and work with a hierarchical set of items. While tree tables are usually used for more complex data, trees are generally used for rather basic data. Trees are mostly used in the master list for a master-detail scenario using the flexible column layout and in popovers or dialogs. In certain use cases, they can also be used in the dynamic page layout.

    In the case of tree tables and trees, items that contain additional items are called nodes, while items that do not contain any other items are called leaves. If available, a single topmost node is called a root node. Apart from the hierarchical structure of its nodes and leaves, a tree is quite similar to a list.

    Usage

    Use the tree if:

    • You need to display the key identifier of hierarchically structured items (for example in the first column of the flexible column layout).
    • Selecting one or more items out of a set of hierarchically structured items is a main use case.
    • The hierarchy has a restricted number of levels (up to about 12, depending on the content) and items (around 200).
    • You want to have only one implementation for all devices.

    Do not use the tree if:

    • The main use case is to select one item from a very small number of non-hierarchical items, without viewing additional details. In this case, a select or combo box might be more appropriate.
    • Items are not structured hierarchically. Use a list instead.
    • The hierarchy turns out to have only two levels. In this case, use a grouped list.
    • The hierarchy turns out to be just a categorization based on several details of the item. In this case, an analytical table provides multi-level grouping. Note that the analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You need to display very deep hierarchies with additional data per item. In this case, use a tree table. Note that the tree table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • The structure contains more than around 200 items. In this case, use the tree table. It is optimized for large item sets and provides better performance. Note that the tree table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You need an overview of a large amount of data. In this case, use a chart.

    Check out the table overview to decide which SAP Fiori table is most suitable for your needs.

    Responsiveness

    The tree is like a list containing hierarchical data. It acts as a container for items, with the possibility to expand and collapse nodes. When reducing the width, item texts wrap to ensure that the tree adapts to the new size.

    In addition, the tree changes the indentation per level dynamically when the user expands a node, based on number of levels currently showing.

    Tree displaying 2 levels
    Tree displaying 2 levels
    Tree displaying 3 levels
    Tree displaying 3 levels
    Tree displaying 4 levels
    Tree displaying 4 levels

    Layout

    The title bar (optional) contains the title of the tree. In addition, an item counter and toolbar items can be placed on the title bar.
    The collection of hierarchical items occupies the main part of the tree.

    Schematic visualization of the tree
    Schematic visualization of the tree

    Components

    The title bar consists of a toolbar. The toolbar can contain a title, an item count, and other toolbar items such as actions or view settings, for example.

    The standard tree item consists of:

    • A highlight indicator (optional)
    • An expand/collapse button for nodes
    • A selector in form of a checkbox or a radio button (optional)
    • An icon (optional)
    • A text
    • A counter (optional)
    • Additional buttons with actions such as Edit, Navigate, or Delete (optional)

    If additional controls are needed, use a custom tree item. The custom tree item allows you to use any combination of controls inside the tree.

    Standard tree item
    Standard tree item

    Behavior and Interaction (incl. Gestures)

    Tree Level

    Scrolling

    The height of the tree is defined by the number of items it contains. It does not have its own scroll container, but is scrolled together with the app.

    Same tree, with different expand state
    Same tree, with different expand state

    When the user scrolls, the title and the filter infobar can stick to the top of the surrounding layout container (sap.m.Tree, property: sticky).

    Information
    The “sticky” feature comes with some limitations:

    • It is not available on all browsers. In non-supporting browsers, the corresponding areas are not fixed on top of the surrounding layout container while scrolling.
    • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the table is placed within the object page.
    • If focus is set to a sticky area, the tree is automatically scrolled to top.

    Sticky title
    Sticky title

    Selection Modes

    A tree can have one of the following selection modes (sap.m.Tree / sap.m.ListBase, property: mode):

    None: Items cannot be selected (sap.m.ListMode.None).
    Beware: Items can, nevertheless, use the sap.m.ListType “navigation” which allows click-handling on specific items. This should only be used when the click triggers a navigation to a corresponding item details page.

    Tree without selectable items
    Tree without selectable items

    Single select master: One item of the tree can be selected. To select an item, click anywhere on the item. Single select master does not add any visual indication to the tree and therefore cannot be differentiated from trees without selection if no item is selected. Therefore, always keep one item selected. For single selection, this is the preferred mode. (sap.m.ListMode.SingleSelectMaster)

    Single selection: Only one item is selected.
    Single selection: Only one item is selected.

    Single select left: One item of the tree can be selected. For this, the tree provides radio buttons on the left side of each line item. Use this selection mode only if clicking on the item triggers something else, such as a navigation. Ideally, always keep one item selected, even in initial state (sap.m.ListMode.SingleSelectLeft).

    Single selection with radio buttons. Use only if row clicks are used for something else, for example navigation.
    Single selection with radio buttons. Use only if row clicks are used for something else, for example navigation.

    Multiple selection: Allows the selection of one or more items. For this, the tree provides checkboxes on the left side of each line item. Each item is selected independently of the others. The Shift key can be used to select a range. Users can (de)select all items using Ctrl+A. Select All should (de)select all items that the user can reach by scrolling. (sap.m.ListMode.MultiSelect).

    Developer Hint
    In multiple selection mode, users can (de)select all items using the shortcut Ctrl+A. This only affects items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded (for example, items added via lazy loading with growingScrollToLoad). This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

    Also note that Ctrl+A only (de)selects items within expanded nodes.

    To process all items, listen to the selectionChange event and to its flag selectAll. This indicates whether Ctrl+A was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

    Guidelines

    • Never disable the selection checkbox. 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.
    • For single-selection master-detail scenarios within the flexible column layout, use the mode “single select master”. Do not show an additional “navigated” indicator.
    • Avoid the mode “single select left”. It removes the possibility of clicking somewhere on the item to select it. Use it only if it is really necessary to have two different click areas; a small one for a selection, and the rest of the item for something else.
    • If selecting / deselecting all items is important for your app, add a button Select All to the toolbar. Change the button text to Deselect All if all items are selected.

    Multiple selection
    Multiple selection

    Deleting

    To delete single items, use the tree in “delete” mode (sap.m.Tree / sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This adds a Delete  button to each item. Clicking this button triggers the deletion of the corresponding item. Do not use this mode if deleting multiple items at once is the preferred use case. Delete is a mode of the tree and  therefore cannot be used together with single selection or multi selection.

    Tree in 'delete' mode
    Tree in 'delete' mode

    Line Item Level

    Expandable and Collapsible Nodes

    An Expand/Collapse button is provided automatically for each node.

    Expand/collapse button
    Expand/collapse button

    Highlight an Item

    To highlight an item, use the “highlight” indicator (sap.m.TreeItemBase, properties: highlight).

    Highlighted item
    Highlighted item

    Navigating

    To allow navigation from an item, set type to “navigation” within the corresponding item (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This will create an indicator at the end of the line (“>”) and the entire item will become selectable. Clicking the line triggers the navigation event. However, clicking a selectable area or an expandable/collapse node does not. Use the navigation event to navigate to a new page containing item details.
    If no navigation is possible, set type to “inactive”.
    Navigation is an item type and therefore cannot be used together with “edit” or in combination with click events for the entire item (“active”).

    Tree items with navigation indicator
    Tree items with navigation indicator
    Navigation indicators can be set per item
    Navigation indicators can be set per item

    Indicate Navigated Item

    When multi-selection is used in a master-detail scenario, it is not clear which item was last opened (for example, which item is currently shown in the second column of a flexible column layout). In this case only (multi-selection tree with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.TreeItemBase, property: navigated).

    Navigated item
    Navigated item

    Editing Items

    To allow the user to edit an item, set type to “detail” within the corresponding item (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive). This will create an edit  button at the end of the line. Clicking the button triggers the edit event. Use this event to either open a dialog or a details page where the item can be edited.
    Edit is an item type and therefore cannot be used together with “navigation” or in combination with click events for the entire item (“active”).

    Edit button
    Edit button

    Clicking an Item

    Items as a whole can be clickable. An event is fired by clicking on the item (anywhere except when triggering a selection or when expanding/collapsing a node). Apps can react to the event, such as by opening a dialog (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Active or sap.m.ListType.DetailAndActive).
    Active elements do not have a visual indication and therefore cannot be differentiated from non-active elements.
    “Active” is an item type and  therefore cannot be used together with “navigation” or “edit”. In addition, “active” uses the entire item as a clickable area and thus cannot be used together with single select master.

    Active items
    Active items

    Context Menu

    You can attach a context menu (sap.m.Menu) to a tree. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

    The context menu can be triggered for the tree or per item.

    Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or Shift+F10.

    Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

    If a control inside a tree is the “click target”, and the control also provides a context menu, the control context menu “wins”.

    Tree - Context menu
    Tree - Context menu

    Drag and Drop

    One or several items can be repositioned within a tree or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

    Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

    Drag and drop is only available on supporting browsers.

    Drag and drop
    Drag and drop
    Whole item as drop target
    Whole item as drop target

    Guidelines

    Tree vs. List

    Trees are more complex than lists due to their hierarchical view. Users tend to have more problems finding items in hierarchical views than in flat lists, except where the hierarchical view is natural. By natural we mean that every child node should be part of only one parent, and this relationship between the child and parent is clear and well known.

    Example of an acceptable use of trees
    Example of an acceptable use of trees
    Do
    A clear parent-child relationship
    A clear parent-child relationship

    Broad vs. Deep Hierarchies

    When you use trees, you should choose broad hierarchies over deep hierarchies. Deep hierarchies make finding items more complicated. So try to reduce hierarchical levels where possible, especially if the hierarchy is not natural. Ideally, a tree should have a maximum of four levels, the first two of which should contain the most important items.

    Don't
    Avoid unnecessary depth in the hierarchy
    Avoid unnecessary depth in the hierarchy
    Do
    Favor breadth over depth in a hierarchy
    Favor breadth over depth in a hierarchy

    You can use the following methods to reduce hierarchy levels:

    • Avoid a single root node. It is usually not needed.
    • Container nodes at the top level can usually be replaced by tabs or value pickers.
    • Eliminate unnecessary mid-level containers, for example, by combining redundant ones.
    • Exercise care when using a tree due to its overall complexity. The hierarchical structure of the data does not necessarily mean that a tree control is required.
    Acceptable: repeat entries to optimize finding items
    Acceptable: repeat entries to optimize finding items

    Design Concepts

    The tree can be used to display hierarchical data. Unfortunately, trees convey an immediate feeling of complexity. Ideally, show trees only if there is no other option. You should instead try the following:

    • Flatten the data. A list is still complex, but less so than a tree. A combo box might also fit in some use cases.
    • When only two levels are needed, a grouped list control can be used. This works well, where group nodes are used for categorizing their children and where the group nodes themselves do not need to be selectable.
    • Break down the data into manageable chunks. Allow the user to navigate or drill down between them.
    • Use charts with drilldown functionality until the amount of data is more manageable.

    Design for Performance

    To optimize performance, we recommend showing no more than 200 items at once in the tree. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

    Warning
    The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

    The actual limits depend on your concrete scenario, including:

    • The number of rows in the table
    • The number of displayed columns
    • The complexity of the cell content (for example, simple text vs. complex charts)
    • Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
    • The browser being used

    Title

    Use a title only if the title of the tree is not indicated in the surrounding area. If needed, implement the title text by adding a title to a toolbar. Place the toolbar above the tree.

    Do not use a title if it simply repeats text that is already above the tree. For example:

    • A Beverages tree is the only control on a tab labeled Beverages.
    • A section or subsection on an object page contains only one tree.

    Use a title if you need the item count, toolbar, or variant management. To avoid repeating text, feel free to use generic text as a title, such as Items.
    Exception: If the surrounding area contains the title, and both the item count and toolbar can be added to the surrounding area, no additional title is needed.
    Example: An object page (sub-)section contains only one tree. In this case, add the item count and the table toolbar to the (sub-)section header.

    If you use a title, be sure to include the following:

    • A title text for the tree.
    • An (optional) item count using the following format: Title (Number of Items). For example, Items (17). Depending on the use case, either count all items or only leaves (for example, if nodes are mainly used for categorization).

    Remove the item count in the title if there are zero items.

    If possible, keep the toolbar sticky (sap.m.Tree, property: sticky).

    Developer Hint
    Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the tree.

    If you don’t use a title (for example, to avoid repetition), make sure that the tree is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

    Title
    Title
    Title with item count
    Title with item count

    Loading Data

    To indicate that the tree is currently loading items, use the busy state (sap.m.Tree, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

    Tree in busy state while loading data
    Tree in busy state while loading data

    Initial Display

    Think of the initial expandable/collapsible state of a tree. If your structure contains many items on the root level, it might make sense to collapse the whole tree in its initial state.

    In contrast, if the most important items are displayed on a deeper level (if, for example, the parent nodes are simply a kind of categorization), the tree should be expanded up to the first level where the most important items immediately appear.

    Errors and Warnings

    To indicate that the tree contains items with errors or warnings, show a message strip above the tree. On the message strip, provide information about errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

    To indicate an error in a single row, see Item States below.

    For details on displaying errors, warnings, and other messages, see Message Handling.

    Developer Hint
    The sap.m.plugins.DataStateIndicator displays a message strip above the table, which shows binding-related messages.
    Tree containing errors
    Tree containing errors

    Content

    Content Formatting

    To display object names with an ID, show the ID in parentheses after the corresponding object name.

    Place the ID in brackets after the corresponding object name
    Place the ID in brackets after the corresponding object name

    Try not to display an empty tree. If there is no way around this, provide instructions on how to fill the tree with data (sap.m.Tree / sap.m.ListBase, properties: showNoData, noDataText).

     

    Examples:

    • If a tree is initially empty, provide at least a basic text:
      No items available.
      Overwrite this whenever a hint can be provided on how to fill the tree with data.
    • If a tree is used together with a filter bar (as in the list report), and is initially empty, use the following text:
      No filters set. To start, enter your search and filter settings and run the search.
    • If a tree is used together with a filter bar and the filter does not return results, use the following text:
      No items found. Check the search and filter settings.

    Adapt the texts above if:

    • The text is not precise enough for your use case (for example, no search is offered, only the search is offered).
    • You are using the live search (no Go button in the filter bar). In this case, leave out “run the search”.
    • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).
    Provide meaningful instructions within an empty tree
    Provide meaningful instructions within an empty tree

    Highlighting Items

    To show that an item needs attention, you can display a highlight indicator in front of the item. The highlight indicator can be used to indicate:

    • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
    • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
    • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

    Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

    For details on the use of highlight colors, see How To Use Semantic Colors.

    (sap.m.ListItemBase, property: highlight)

    Highlighted items
    Highlighted items

    Item States

    To show that an item has been modified, for example within the global edit flow, add the string (Modified) to the text of the item.

    A modified item
    A modified item

    To show that a modified item contains an error, for example within the global edit flow, add the string (Contains errors) to the text of the item and highlight the row accordingly.

    A modified item with an error
    A modified item with an error

    To show that an item is locked, add the string (Locked by [name]) to the text of the item.

    A locked item
    A locked item

    To show that an item is in a draft state, add the string (Draft) to the text of the item.

    Item in draft state
    Item in draft state

    Show only one state at any one time.

    Actions

    To trigger actions on items, show the actions on a toolbar above the tree. Do not offer action triggering on multiple items if the tree is expected to have fewer than 10 items in most cases.
    The following actions on single items must always be in-line:

    Delete: Use “Delete” mode (sap.m.Tree / sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This places a Delete  button at the end of each item.

    Items with 'Delete' button
    Items with 'Delete' button

    Navigation: Use the “Navigation” item type (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This places a navigation indicator at the end of the corresponding items. Use this to navigate to a new page containing item details.

    Items with navigation indicator
    Items with navigation indicator

    Edit: Use the “Detail” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail). This places an Edit   icon at the end of the corresponding items.

    Edit button
    Edit button

    From these three actions (delete, navigation, and edit), you can combine delete and edit, or delete and navigation. Edit and navigation cannot be combined.

    To trigger actions that are independent of the selection, show the actions on a toolbar above the tree. For example: Add, Collapse All, Expand All, …

    To trigger a default action on the entire item, use the “Active” or “DetailAndActive” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Active). Active items trigger an event when clicked, which can be handled by apps, for example, to open a dialog. Selection and expanding/collapsing a node does not trigger the event, but are handled by the tree. Do not use this for navigation, to switch the line item to an edit state, or to delete the item.
    Active can be combined with edit and delete, but not with navigation. Do not combine active with single selection master.

    Add Items

    For adding items, place an Add or Create text button on the tree 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.

    Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

    Show new items as the first item of the tree or node:

    • If nothing is selected, add the new item to the root.
    • If a single node is selected, add the new item to the selected node.
    • If a single leaf is selected, add the new item as a child of this leaf. The original selected item becomes a node.

    If your tree doesn’t support adding items to the root, selected node, or selected leaf, disable Create or Add for the corresponding levels.

    Disable Create or Add if more than one item is selected.

    There are three options for adding an item. In order of priority (most recommended first), these are:

    1. Add the item inline. Create an empty, editable item as the first item of the selected node. Show the Save button on the tree toolbar. This option is recommended for simple scenarios where just a few input fields have to be filled.
    2. Open a dialog for items where up to 8 input fields need to be filled. Save the new item at 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, creating complex objects). When the user presses Save in the footer toolbar of the create page, navigate back to the tree.

    Depending on the flow, an item can be in one of three different states:

    • New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
    • Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the corresponding node. Ignore current sort, filter, and grouping criteria to keep the item visible.
    • Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
      • Inline creation: After Save was triggered on the tree toolbar or at page level.
      • Create with dialog: A tree showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

    In the context of draft handling, new items are not saved at tree level, but rather with the entire draft.

    For more details, see the guidelines for managing objects (including subarticles).

    Enabling/Disabling Actions

    To indicate if an action can be applied to the current selection:

    • Enable the action if it always works, regardless of whether or not items are selected.
    • Enable the action if it can be applied to all selected items.
    • Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that tells the user how many items will be affected. Let users choose whether to apply the action anyway or cancel the action.
    • Only disable the action if it can be applied to none of the selected items.

    For more details, see UI Element – States.

    If the action was applied and the items are still available, keep them selected.

    Message for an action that applies to a part of a selection
    Message for an action that applies to a part of a selection

    Editing Items

    To edit items, add an Edit button either in-line on the toolbar above the tree. Triggering the button either opens a dialog or navigates to an editable details page.

    For mass editing:

    • Provide multiselection (sap.m.Tree/ sap.m.ListBase, property: mode, value: sap.m.ListMode.MultiSelect).
    • Provide an Edit button on the toolbar above the tree.
    • If several items are selected, triggering the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

    For more details, see mass editing.

    Context Menu

    Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

    Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

    Drag and Drop

    Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, 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. These are keyboard operable and available on all browsers.

    Use drag and drop only in addition to existing visible UI elements
    Use drag and drop only in addition to existing visible UI elements

    If you offer drag and drop for rearranging items within a tree, use the following options:

    • For dropping items as a child, use whole nodes as drop targets (sap.ui.core.dnd.DropPosition.On).
    • For dropping items on the same level, use the space between items as drop targets (sap.ui.core.dnd.DropPosition.Between).
    • If you want to allow users to drop items as a child or sibling, offer both drop targets (sap.ui.core.dnd.DropPosition.OnOrBetween).

    This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

    Do not combine rearranging items within one level and sorting. If you really need to do so, make sure there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

    Moving items from one node to another can be combined with sorting without any issues.

    Drop targets in between items
    Drop targets in between items

    Visible Alternatives to Drag and Drop

    Depending on the functionality you need, use one or more of the following alternatives:

    • To move items up or down within a node:
      Use the  Move Up and  Move Down buttons on the toolbar. These buttons move the selected items until the first selected item can’t be moved up or the last selected item can’t be moved down any further.
      Depending on your tree, this can make sense for both leaves and nodes, only for leaves, or only for nodes. When moving a node, move the whole node and (if applicable) all its children up or down to the next position within the parent node.
      Always make sure that when the user moves an item in one direction and then moves it back, the order is the same as it was before.
      Do not combine the option to move items up and down with sorting.
    • To move items to another node:
      Use Copy and Paste buttons on the toolbar.
      Alternatively, offer a Move To button. Clicking Move To opens a dialog that shows all the nodes of the tree, but no leaves. Selecting an item in this dialog closes the dialog and moves the corresponding items to the selected node.
    • To change the level of an item:
      In some trees, such as document structures, users can change the level of an item without affecting the level of parent or child items. In this case, use left and right arrow buttons (   ).

    Filtering

    What exactly needs to stay or be removed is highly dependent on the kind of structure and data your tree displays. For many trees, the following approach works well if you want to apply filters only to the leaves of a tree:

    • Remove all leaves that don’t fit the filter criteria
    • Remove empty nodes

    If you also apply filters to nodes, keep the following in mind:

    • A node may or may not fit the filter criteria.
    • A node can contain items (nodes and/or leaves) that fit the filter criteria.

    Because of this, the results might contain more nodes than those that are relevant for the filter criteria.

    Information
    The tree control itself has no influence on the filter result. It sends a filter request and displays whatever comes back. Make sure that the result set is meaningful.

    Sorting

    Before you start, ask yourself if sorting is meaningful in your tree. If so, decide on a meaningful default sort order.

    If sorting is meaningful, is it meaningful on all levels? Or does the tree structure need to be stable? In the latter case, sort only leaves, but not nodes.

    Always sort the tree in a meaningful way when it first loads.

    The descending sort order must always be the exact reverse of the ascending sort order. Use a meaningful sort order. For example:

    • Sort text alphabetically
    • Sort numbers by their value
    • Sort status information by the severity of the status:
      • Ascending: Sort status information from positive to negative, with neutral last.
      • Descending: Sort status information from negative to positive, with neutral first.
      • Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
      • Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

    Export to Spreadsheet

    On the table toolbar, apps can provide a menu button for exporting the tree data to a spreadsheet. For the export, use the export to spreadsheet function.

    'Export to Spreadsheet' menu button
    'Export to Spreadsheet' menu button

    Resources

    Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

    Elements and Controls

    Implementation

    Feed and Notes

    Feeds and notes are commonplace in many SAP Fiori applications. The sap.m.FeedInput control allows users to input and post plain text, while the sap.m.FeedListItem control handles and displays this text. Both can be used individually, but they also complement each other well to create a simple feed or notes control.

    Usage

    Feed Input

    Use the feed input if:

    • A user needs to input small amounts of text without formatting.
    • You expect multiple instances, such as notes or feed entries.

    Do not use the feed input if:

    • The user needs to format the text (rich text editor).
    • You need only a single text box instance. In this case, use the text area (for multiple lines) or the text control (for a single line).

    Combination of Both Controls (as Feed or Notes Control)

    Use both controls if:

    • You need a feed to show textual posts.
    • Your users need to input notes.

    Do not use both controls if:

    • You expect extensive social interaction in the feed.
    • Users need to reply at item level instead of creating a new post.
    • You want to display SAP Jam feeds.

    In these cases, use the social timeline instead (requires SAP Jam).

    Responsiveness

    Due to their responsive behavior, both controls can be used in small and large view ports or screens.

    For better usability, we highly recommend that you do not stretch the controls across the full width on large screens – 2/3 or even 1/2 works just fine. This can easily be achieved using the grid layout .

    Feed – Size S
    Feed – Size S
    Feed – Size M
    Feed – Size M
    Feed – Size L
    Feed – Size L

    When the width of the available space falls below 25 rem (for example, in portrait mode on smartphones), the two controls respond as follows:

    • If a user image previously appeared in the feed input, it will be omitted in narrow screens to give the text field more space.
    • If there is no user image, there will be no visual change.
    Feed input – Responsiveness
    Feed input – Responsiveness

    In the feed list item, the user’s name, image, and the time stamp move on top of the text. If there is no image, the name and time stamp are left-aligned together with the text.

    Feed list item – Responsiveness – With image
    Feed list item – Responsiveness – With image
    Feed list item – Responsiveness – Without image
    Feed list item – Responsiveness – Without image

    Layout

    Feed Input

    The feed input consists of:

    • A text input field with a placeholder (input prompt)
      Example: Add a comment
    • A Send button
    • An optional user image

    You can also choose not to show user images at all. In this case, the size of the input area increases automatically.

    Feed input – Layout – With user image
    Feed input – Layout – With user image
    Feed input – Layout – With generic user image
    Feed input – Layout – With generic user image
    Feed input – Layout – Without user image
    Feed input – Layout – Without user image

    Feed List Item

    The feed list item consists of the user’s name and an optional picture of the user who wrote the note or update. The name can contain a link that triggers a quick overview of the user’s profile data. The actual text written by the user follows the name. Below it is a separate byline that can contain a time stamp and an attribute in the form of free text. This allows you to put in your own attribute, such as Approval, Internal, or External. Both the time stamp and the attribute are optional.

    If the name is a link, the picture should also be linked with the same attributes.

    Feed list item – With user image and linked name
    Feed list item – With user image and linked name

    If the user does not have a picture assigned, a placeholder is shown instead:

    Feed list item – With generic user image and linked name
    Feed list item – With generic user image and linked name

    The name (and picture) can also be read-only, that is, without a link:

    Feed list item – With user image but without links
    Feed list item – With user image but without links

    If the app does not support user images, they can be omitted:

    Feed list item – Without user image but with linked name
    Feed list item – Without user image but with linked name

    Here, too, the name can be read-only:

    Feed list item – Without user image and read-only name
    Feed list item – Without user image and read-only name

    It’s also possible to display rich text (formatted text) in the feed list item. This feature should be handled with care as it allows for countless custom layouts.

    Please see that you use it responsibly and provide your users with a consistent experience. Only deviate from the default layout and font if absolutely required by the use case.

    Example use case: Render URLs as links.

    Feed list item – Layout – Rich text
    Feed list item – Layout – Rich text
    Information
    The items in the feed list must be homogeneous. This means that they must contain the same layout and visualization. For example, it is not possible to have a feed containing both linked and plain names, or both user images and default images.

    Special Case: Multiple Types of Notes

    Apps sometimes need to discern between different types of notes. There is an easy way to allow users to choose which type they want to see or add to the list.

    You can place a toolbar containing a select control at the top of the feed input control. From there, users can select the type of notes, such as Internal Notes or External Notes. The list of notes must contain only the type selected. If the user adds a note via the feed input, the type must be set automatically according to the selection.

    Interaction – Note Types

    Components

    The feed input and feed list item do not contain subcontrols. However, you can easily combine them to create a simple feed or notes control.

    Although the feed input counts as a single control, the input area inherits its behavior from the sap.m.TextArea control.

    Behavior and Interaction

    Send Message

    Initially, the feeder contains a placeholder (input prompt), and the Send button is disabled, with reduced opacity.

    Clicking into the input field puts the focus on the field and allows to start typing.

    When the user starts to type, the placeholder disappears and the Send button becomes active and more prominent.

    If the available width is below 25 rem (for example, in portrait mode on a smartphone), the picture is removed.

    To send the text, the user must explicitly click the Send button. Pressing Enter on the keyboard (on-screen or physical) results in a line break.

    Feed input – Behavior
    Feed input – Behavior

    Show More Text

    When the text exceeds a certain number of characters (you can overwrite the default value), the rest of the text is truncated and a MORE link appears after the truncated section.

    The MORE link indicates the possibility of expanding the section of the feed list item itself. Hovering over the link underlines it.

    Show Less Text

    When the user expands the text, the name of this link changes to LESS,  but still behaves the same way as before.

    Modify “MORE” / “LESS” links to “More / Less” to be consistent with other components.

    More link
    More link

    Feed and Notes in Tables

    In tables, users sometimes need to see if an object has a comment (or feed or note) without further navigation, and even be able to add/edit right from the table.

    Add an additional column, named according to the type of user input, such as Comment, Note, or Feed.

    Place a link inside each cell with the appropriate action (row: Comment, link: Comment / row: Feed, link: Post).
    If there can be more than one item, add a counter after the text as well (see example on the right).

    This solution works with every table control.

    Feed and notes in tables (1)
    Feed and notes in tables (1)

    Optional:
    Depending on the use case, it might help users if they can see the latest note. The responsive table allows the feed list item (sap.m.FeedListItem) to be used inside a cell.

    Reduce the property “maxCharacters” to an amount that your table can handle.
    Note that once the maximum number of characters has been reached, a MORE link allows users to expand the text. Technically, this is no problem for the responsive table, but you need to ensure that the layout of your page allows this kind of expansion.

    Place a link below the feed list item to allow users to add something (as described above).

    Feed and notes in tables (2)
    Feed and notes in tables (2)

    When the user clicks a link, such as Comment or Note, display a dialog showing all comments (notes, feed entries, and so on) along with possible actions, such as Add or Edit, depending on your use case.

    There are several ways to show notes (comments, feed entries, and so on) in a dialog:

    • You can use the feed list item (and feed input) as described in this article.
    • If only one single note is allowed, you can use the text area.
    • For a large feed, you can use the timeline control (SAP Jam is required for social features).

    Actions On Feed List Items

    Applications can define actions that users can perform on individual feed posts. The two most typical actions are Edit and Delete. Other actions can be introduced as required by the use case. To keep the feed as lightweight as possible, don’t overwhelm users with too many actions or complicated actions (max. 5 per post).

    Interaction - Actions
    Interaction - Actions

    Styles

    By default, feed entries are separated by divider lines. We recommend that these separators remain enabled, since they help distinguish between individual posts. However, if your list is expected to hold only a handful of entries, you can disable the separators by setting the showSeparators property at list level (not at list item level) to none.

    Guidelines

    Because the feed list item is built on the basis of the standard list item, it inherits multiple properties that may not make sense in a feed use case.

    Use only properties that are described in this article. Especially making the entire feed list item clickable can lead to functional issues and usability problems.

    Don’t stretch the feed input or the feed list items across large screens (size L and beyond). This will have a negative effect on usability and readability. Instead, only use 1/3 or even 1/2 of the screen. Implement this with the grid layout .

    If you display formatted text (rich text) in the feed list item, use formatting that is beneficial to users, not decorative formatting. Use formatting responsibly, and provide your users with a consistent experience. Deviate from the default layout and font only if absolutely required by the use case (example: render URLs as links).

    Resources

    Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

    Elements and Controls

    • No links.

    Implementation

    Message Page

    The message page gives feedback to the user when an empty state occurs at page level, such as an empty app or list. The message page explains what information would normally appear on the page and how the user can proceed.

    When To Use

    Use the message page if:

    You need to give feedback on an empty state at page level. You can use the message page in the following situations:

    • Searching and/or filtering with no results
    • Empty app
    • Too many items (search or filtering required)
    • Item saved as a tile that is no longer available
    • Error

    Do not use the message page if:

    • You want to give feedback on empty states within UI elements, such as dialogs or tables. Use an illustrated message instead.
    • The app is simply loading. In this case, use the busy state without an explanatory text.

    Components

    The message page follows the general message pattern for empty states. It contains an icon, a message headline, a message description, and an optional call to action.

    (1) Icon

    The icon in the message page is mandatory.
    Exception: If you can’t find a suitable icon for your message, leave out the icon.

    (2) Message Headline

    The headline explains the reason for the empty state, preferably in a single line. Use the headline to convey the essence of your message in simple, engaging language.

    Write the headline in sentence case without an ending period (.)

    (3) Message Description

    The description adds details and tells the user what to do next, in three sentences or less. Write the description in sentence case with proper punctuation. You can also set links in the description and use formatted text (such as bold, italic, underline, and bullet points).

    (4) Call to Action (Optional)

    If there is a clear next step, include a button or buttons with appropriate actions. Do not place more than 2 buttons on a page.

    Responsiveness

    The size of the message page adjusts to fit the available space.

    Size S (Smartphone)

    Search with no results on a smartphone
    Search with no results on a smartphone

    Size M (Tablet)

    Search with no results on a tablet
    Search with no results on a tablet

    Size L (Desktop)

    Search with no results on a desktop device
    Search with no results on a desktop device

    Examples

    The following examples show some typical message page use cases and how messages can be formatted.

    Search

    The user has searched for something but there are no results:
    • Icon: Search
    • Message headline: No matching items found
    • Message description: Try changing your search criteria.
    Search with no results
    Search with no results

    No Items

    The app contains no items (here: suppliers).
    • Icon: Product icon, or an icon that matches your use case.
    • Message headline: There are no suppliers yet
    • Message description: When there are, you’ll see them here.
    No products can be shown
    No products can be shown

    Error

    The app cannot show any content due to an error:

    • Icon: Document
    • Message headline: Sorry, we can’t find this page
    • Message description: Please check the URL you are using to call the app.
    Error case – With link
    Error case – With link

    Formatted Text and Buttons

    Message page with buttons
    Message page with buttons
    Message page with formatted text
    Message page with formatted text

    Top Tips

    • Always include an icon, a message headline and a description with further details.
    • Do not show only the state of the message (like error or warning), but rather try to describe the problem. Help the user to recognize, diagnose, and resolve the issue.
    • Keep your message as concise as possible.
    • Do not show the No data  message, which could mislead users.

    Related Links

    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.

    Predefined Sizes of the Status Indicator (S, M, L, XL)

    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

    Circular Fill

    For round shapes, you can use the 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

    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

    Busy State

    You can set a busy state for each SAPUI5 control. This function adapts to the space available on the UI.

    When to Use

    Use the busy state of the control if:

    • The operation takes more than one second (busy state set at control level)
    • You want to indicate that data is loading on a table or on a list after performing a search or filtering (set the busy state at table or list level).

    Do not use the busy state if:

    • The operation lasts less than one second.
    • You expect several busy states at once. In this case, consider setting the busy state at a higher level or container.

    Examples

    Busy page
    Busy page
    Busy buttons
    Busy buttons

    Guidelines

    Avoid showing multiple busy states at once. If you expect multiple busy states on various controls, you can set the busy state on a control or container above.

    In some cases, however, it makes sense to allow multiple busy states. For example, a page could contain a form and several tables that load asynchronously. In this case, it does not make sense to set the busy state at page level until all the data is loaded as the user can start filling out the form which is already available. Response times may vary due to table data retrieval from different services.

    Try to enable as much as possible on one screen,so the user can start working while the rest of the data is being loaded in the background. Set the busy state for those UI elements that will require some time to load.

    Resources

    Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

    Elements and Controls

    Implementation

    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 Columns tab 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 Sort tab 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 Filter tab allows the user to filter the table information according to specific criteria.

    Users can add filters with the Add button or remove them by clicking the  (Remove Filter) icon at the end of each filter item.

    Column

    In the first input field, the user selects the column to be filtered. Any column can be selected, including columns that are not currently visible.

    Operator

    The second field contains the operator that is applied to the filter value (such as greater than or not before).

    To include or exclude filter criteria, users select the relevant operator from the Include or Exclude section of the dropdown list. For example, equal to to include a value, and not equal to to exclude it.

    If individual filter criteria have Boolean values, the operator is always “equal to” and the operator dropdown is disabled.

    P13n Filter Settings

    • P13n filter tab
    • Filter with date picker
    • Filter with input field/suggestions
    • Filter with disabled operator dropdown

    Available operators:

    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

    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 and the selected operator. For example, the value field for fixed or boolean values could be a dropdown list, and input field with suggestions, or a date picker. Two or even more fields can be provided, as required by the use case.

    Information
    If there is a filter bar, use the filter bar functionality and deactivate the filter feature of the P13n dialog.

    Group

    The Group tab 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

    Message View

    Intro

    You can use the message view to display messages that are not related to form or table fields. These messages are triggered in response to a user action.

    Although the message view can be embedded within various controls, we recommend that you use it only within a dialog.

    Message view
    Message view

    Usage

    Use the message view if:

    • You want to display multiple messages triggered by an action within a disruptive dialog.

    Do not use the message view if:

    • You want to display messages for form field validation. Instead, use the message popover.
    • You want to display a single message that interrupts the user. Instead, use the message box.

    Responsiveness

    Size S (Smartphone)

    The responsiveness of the message view is determined by the dialog container in which it is embedded.

    Layout

    Filtering

    Multiple Message types – Filtering by Message Severity

    If different types of message are available, users can filter messages by type (error, warning, success, and information) using the segmented buttons at the top of the message view.

    Messages of different types can be filtered using the segmented buttons.
    Messages of different types can be filtered using the segmented buttons.

    One Message Type Only – Filtering Hidden

    The filter bar is hidden if there is only one type of message (for example, only errors).

    The filter bar is hidden if all messages are of the same type.
    The filter bar is hidden if all messages are of the same type.

    List

    Short Description (1)

    A simple and helpful short message text.

    Subtitle (2)

    You can use the subtitle to give your message a description that helps users to identify the object they are looking for.

    Navigation to Message Details (3)

    If message details are provided, the message view automatically provides a chevron on the right-hand side for navigating to the message details.

    Aggregating Messages (4)

    You can aggregate messages by filling out the counter property of each list item.

    Information

    • The message popover only provides the counter property. The aggregation itself must be implemented by the app team.
    • When 2 or more messages are aggregated, the message short text cannot be a link because there would be multiple targets.

    Message view list items
    Message view list items

    Message Details

    The detail view has the following parts:

    1. Back-end short text

    2. Back-end long text

    3. Optional link

    Message view detail page
    Message view detail page

    Behavior and Interaction

    Navigation to Message Details

    If the backend contains a long text, the user can click the arrow/chevron on the right-hand side to view the full text in the message details.

    Navigation to message details
    Navigation to message details

    Life Cycle

    We recommend that messages no longer be displayed after the user closes the dialog (sap.m.MessageBox/sap.m.Dialog).

    Resources

    Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

    Elements and Controls

    Implementation

    Message Popover

    The message popover control can display multiple messages of different types in one list. For example, it might show several messages related to entries in a form, or messages triggered by a finalizing action, such as Save.

    The message popover is used in conjunction with a technical message manager, which populates the message list. If an error occurs at a validation point, the corresponding message is added to message popover automatically, without interrupting the user.

    Users can browse messages by type and navigate to the message details. In some cases, they can also jump directly from the message to the affected field on the UI.

    Message popover
    Message popover

    When to Use

    Use the message popover if:

    • You want to display multiple messages to the user.
    • You do not want to interrupt users while they are performing an action.

    Do not use the message popover if:

    • You need to interrupt the user. In this case, use a message box.
      (Typically, interrupting the user is only necessary for technical problems, such as network errors and connection issues.)

    Components

    (1) Filter bar
    (2) Short description
    (3) Subtitle
    (4) Section/subsection on the UI
    (5) Message button
    (6) Navigation to message details
    (7) Counter for aggregated messages

    Components of the message popover
    Components of the message popover

    Filter Bar

    Initially, the filter bar shows all the different message types in the list (1).

    Segmented buttons at the top of the message popover allow the user to filter the messages by type (error, warning, success, and information).

    List

    Short Description (2)

    A simple and helpful short message text. It’s the same message as the one attached to the UI control where the issue occurred.

    Subtitle (3)

    You can use the subtitle to give your message an identifier. If the message relates to a specific field, show the label of the field where the error occurred. Based on the subtitle, the user should be able to identify the corresponding UI control on the UI (for example, the input field in a form).

    Section/Subsection (4)

    Messages in the list are grouped by the section and subsection on the UI. This helps the user to find the part of the UI that triggered the message.

    Navigation to Message Details (6)

    If message details are provided, the message popover automatically provides a chevron on the right-hand side for navigating to the message details page.

    Aggregated Messages (7)

    If you want to aggregate messages, you can use the counter property of each list item.

    Information

    • The message popover only provides the counter property. The aggregation itself must be implemented by the app team.
    • When 2 or more messages are aggregated, the message short text cannot be a link because there would be multiple targets.

    Message Button

    If there are messages to display, the message button indicates the most critical message status in the list (5).

    For example, if the list contains error messages, the message button inherits the error icon and semantic color. If the most critical message in the list is a warning, the message button shows the warning icon and corresponding semantic color, and so on.

    In addition, the error button contains a count indicating the number of errors.

    Message button types - Error with counter, warning, success, information
    Message button types - Error with counter, warning, success, information

    If there are no messages to display, there is no message button. In this case, the footer toolbar contains only the “normal” actions for the task.

    Message Details

    The message details page shows:

    • The message short text (1).
    • A more detailed message text to explain the issue and propose a solution (2).
    • An optional link to more information, such as app documentation (3).
    Detail page of the message popover
    Detail page of the message popover

    Behavior and Interaction

    When Does the Message Popover Open?

    Form Field Validation

    If one or more errors occur when the user fills out a form, the message button appears, indicating the message type of the most critical message. The message popover does not open automatically. For more information on the different validation points, see Form Field Validation.

    Form field validation behavior
    Form field validation behavior

    Finalizing Actions

    If the user activates a finalizing action (such as Create, Save, or Submit), the message popover opens automatically to inform the user about the errors on the UI that need to be resolved first.

    Message popover triggered by a finalizing 'Save' action
    Message popover triggered by a finalizing 'Save' action

    Navigation to Message Details

    If the message provides a long text from the back-end system, the user can navigate to the message details. There, the user will typically find more information and help.

    Navigation to message details
    Navigation to message details

    Navigation to the Relevant Field

    The navigation link takes users directly to the field on the UI that triggered the message. This can be a field in the visible area, a field somewhere else on the same page, or a field on another tab or screen.

    Guidelines
    Always add a navigation link, where possible.

    For more information about the navigation, see Navigating to the Corresponding Field on the UI in the Message Handling article.

    Developer Hint
    Set the navigation link with the activeTitlePress event. This allows users to click the message text in both the first and second page of the message popover.
    Navigation from the message text to a field on the UI
    Navigation from the message text to a field on the UI

    Responsiveness

    Size S (Smartphone)

    On smartphones, the message popover is automatically shown in full screen mode.

    Full screen message popover on a smartphone
    Full screen message popover on a smartphone

    Top Tips

    • Whenever possible, provide a navigation link from the message to the relevant field on the UI.
    • Use the message subtitle to indicate the field label.
    • In forms, also highlight the individual fields, and change their value state according to the type of message. For more information, see Form Field Validation.

    Related Topics

    Elements and Controls

    Implementation

    Message Box

    The message box (sap.m.MessageBox) is a special dialog that allows you to display messages to the user. Compared to the message popover (sap.m.MessagePopover), you can use the message box to display messages that are not related to a field on the UI, such as technical errors.

    Formulate messages in plain language (no code), describe the issue precisely, and suggest a constructive solution. Always help your user to recognize, diagnose, and recover from messages. Bear in mind that no message is always preferable to even a good message. When you design your apps, aim to prevent problems from occurring in the first place.

    Usage

    Use the message box if:

    • You want to display non-field-related messages.
    • You want to interrupt the user while he or she performs an action.
    • You want to display error, warning, success, confirmation, or information messages.
    • You need to interrupt the user for some other reason.
    • You need the user to acknowledge the message.
    • You need the user to make a decision.

    Do not use the message box if:

    • You want to display a short success message. (Use a toast instead. For more information, see message toast.)
    • You can show the message directly in a form field.

    Responsiveness

    The sap.m.MessageBox control has the same responsive behavior as the sap.m.Dialog control. The message box should only be opened in modal mode. Its basic width is 25 em. For more information, see dialog.

    Types

    The following categories of messages are available:

    • Error
    • Warning
    • Success
    • Information
    • Confirmation

    Error Message

    Error messages can be triggered after the user has entered incorrect data or a system error has occurred. They should interrupt the user by displaying a dialog. A final action such as Submit cannot be carried out until the user has rectified the error.

    Control: sap.m.MessageBox
    Icon: sap-icon://message-error
    Title: Error
    Stretch: False (no full screen on all devices)

    Error message with one action
    Error message with one action
    Error message with two actions
    Error message with two actions

    Text guidelines for an error message:

    • Do not just describe the problem; tell the user how to resolve it.
    • In the short text, speak the language of the end user. Do not include system or configuration details.
    • If the solution is more involved or technical, add a long text.
    • Do not repeat the short text in the long text. They both appear together on the screen.

    Warning Message

    Warning messages highlight potential issues, but the user can still continue. This includes unintended data loss scenarios.

    Control: sap.m.MessageBox
    Icon: sap-icon://message-warning
    Title: Warning
    Stretch: False (no full screen on all devices)

    Use cases for warnings

    a) No decision required: Formulate the message as a statement.
    Button(s): OK

    Warning message with 'OK' button
    Warning message with 'OK' button

    b) Decision to continue required: Formulate the message as a statement.

    Button(s): OK, Cancel

    Warning message with 'OK' and 'Cancel' buttons
    Warning message with 'OK' and 'Cancel' buttons

    c) Specific decision required, with one action

    Use a relevant action button. The message may also be formulated as a question.
    Button(s): Leave Page, Cancel

    Warning message with action and 'Cancel' buttons
    Warning message with action and 'Cancel' buttons

    Success Message

    Success messages give feedback to the user that an action has been executed. The user needs to acknowledge the message.

    Control: sap.m.MessageBox
    Icon: sap-icon://message-success
    Title: Success
    Stretch: False (no full screen on all devices)
    Button(s): OK

    Success message
    Success message
    Information
    You should generally use a message toast (sap.m.MessageToast) to display success messages instead of a dialog (sap.m.Dialog).

    Information Message

    Information messages provide information the user needs to acknowledge, but which does not involve a decision. The message provides information that is useful and relevant, but never critical.

    Control: sap.m.MessageBox
    Icon: sap-icon://message-information
    Title: Information
    Stretch: False (no full screen on all devices)

    Button(s): OK

    Information message
    Information message

    Confirmation Message

    Confirmation messages prompt users to confirm an action that they have triggered. The title of the message box already includes the action that has to be confirmed, such as an intended deletion or an approval.

    Control: sap.m.MessageBox
    Icon: sap-icon://question-mark
    Title:  (such as “Approve”, “Reject”, or “Delete”)
    Stretch: False (no full screen on all devices)

    Button(s): Approve, Cancel

    Confirmation message
    Confirmation message

    Confirmation Message with “Note” Section

    Warning
    The image belows shows a “Note” section which allows the user to add notes, for example in a “Reject” process. This feature is not provided by the sap.m.MessageBox. Instead, you can use a normal sap.m.Dialog and place those controls inside the confirmation message.

    Confirmation messages prompt users to confirm an action that they have triggered. The title of the message box already includes the action that needs to be confirmed, such as an intended deletion or an approval.

    Control: sap.m.Dialog
    Type: Message
    Icon: sap-icon://question-mark
    Title:  Such as “Approve” or “Reject”
    Stretch: False (no full screen on all devices)

    Button(s): Approve, Cancel

    Confirmation message with note
    Confirmation message with note

    Confirmation for “Delete”

    If the user clicks Delete, display a “Delete” dialog that confirms the delete action.

    Control: sap.m.MessageBox
    Icon: sap-icon://message-warning
    Title: Delete
    Stretch: False (no full screen on all devices)

    Button(s): Delete, Cancel

     

    Use cases for delete confirmation messages in object page and list reports

    a) No context is available. For example, neither the ID nor the description of the business object are available at the time of deletion.
    Body text: Delete this <object>?

    Confirmation for 'Delete' action
    Confirmation for 'Delete' action

    b) The ID of the object is available.
    Body text: Delete <object> <object ID>?

    Confirmation for 'Delete' action with object ID
    Confirmation for 'Delete' action with object ID

    c) The object ID and description are both available at the time of deletion.
    Body text: Delete <object> <object ID> “<object description>”?

    Confirmation for 'Delete' action with object ID and description
    Confirmation for 'Delete' action with object ID and description

    Deleting several objects

    If more than one object is being deleted, do not display the object ID and description.
    Body text: Delete the <n = optional> selected <objects>?

    Confirmation for 'Delete' action with several objects
    Confirmation for 'Delete' action with several objects
    Developer Hint
    The default text in SAP Fiori elements will be slightly different, usually using the default term “object” to designate the item to be deleted. When using SAP Fiori elements, replace “object” with the correct business object name. For more information, see Introduction to SAP Fiori Elements – Adjustments.

    Components

    The message box contains the following sections and options:

    Title: Title text appears in the message box header.

    Content: This area contains the actual content of the message box.

    Footer with actions: Although the message box allows more than two buttons, we recommend limiting the number to two. Available button types are primary and negative path actions. If you require other button types, use sap.m.Dialog instead. If no buttons are defined, the default Close button is shown.

    Example of a message box structure
    Example of a message box structure

    Show Details button

    The message displayed for the user should provide sufficient information to ensure that the user knows what has happened. A message box without an explicit details section should be sufficient. Therefore, the Show Details link is only shown if detailed information is available that differs from the message text and is important for the user.

    If details are available, the application has three options to display the text. Text can be displayed as:

    • Plain
    • Formatted
    • The original code format
    Message details - Plain text
    Message details - Plain text
    Message details - Formatted text
    Message details - Formatted text
    Message details with code excerpt
    Message details with code excerpt

    Resources

    Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

    Elements and Controls

    Implementation

    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 conditions. 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 is searching within a dataset that contains more than 1,000 items.
    • The user needs to use different attributes to find an object (such as city, company name, and so on).
    • The user needs to define conditions, such as 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 the select control if the user needs to select only one item from a short list.
    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
    2) Icon tab bar / list control (phone)
    3) Search template (optional)
    4) Basic search
    5) Go button
    6) Filters
    7) Result list
    8) Selected items and conditions
    9) Footer toolbar
    10) Area for defining conditions, such as ranges and exclusions

    Components of the Value Help Dialog

    Header (1)

    The header bar contains the dialog title. See the Guidelines section below.

    Icon Tab Bar / List Control (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.StandardListItem), Search and Select, 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 Search and Select and the Define Conditions tab.
    • Both controls have a counter in the title that indicates the number of items/conditions selected.

    Search Template (3)

    Search templates allow the user to display different or additional fields in the filter area and result 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 filter area 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.

    Go Button (5)

    The Go button triggers the search and filters the result list.

    Filters (6)

    The filter area offers a filter field for each column in the result list. In some cases, there can be specific filter fields that do not have a corresponding column on the UI. These fields typically come from the back-end service.

    Value help dialog - Filters
    Value help dialog - Filters

    For the basic search with filters, the filter bar (sap.ui.comp.filterbar.FilterBar) is implemented 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 fields are added automatically to the filter area.
    • There is a toggle button to show and hide the filters.
    • In each of the filter fields, users can use operators like “between” or “lower than” to define conditions.

    Always hide the filter area in the value help dialog by default. Only show the filter area by default if the basic search can’t be provided.

    Note that the value help icon of the Product ID field in the current value help dialog will open only the Define Conditions screen. The full value help dialog is not shown in order to prevent endless loops. For example, the value help icon of the Product Name or Category field in the value help for a Product field will navigate directly to the Define Conditions: Product screen.

    Using the Filters

    Users can enter operators (such as “=“) to define the conditions directly within the field without opening the Define Conditions tab.

    Users must use the following notation to get results:

    Operator Input Notation Example
    between value…value 000…100
    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 between !(value…value) !(000…100)
    not equal to !(=value)  !(=0)
    does not contain !(*value*)  !(*1*)
    does not start with !(value*)  !(001*)
    does not end with !(*value)  !(*5)
    not less than !(<value) !(<100)
    not less than or equal to !(<=value) !(<=200)
    not greater than !(>value)  !(>0300)
    not greater than or equal to !(>=value)  !(>=0500)
    empty <empty>   <empty>
    not empty !(<empty>)    !(<empty>)
    Using an operator to filter the result list
    Using an operator to filter the result list

    Result List (7)

    • The result list is populated on initial load 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. Only the entered (or modified) value is transferred to the basic search. Type-ahead suggestions are ignored. The search is triggered automatically when the dialog opens.
    • 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 result list.

    Selected Items and Conditions (8)

    The selected items and conditions are displayed in a tokenizer (see token for more information). Each selected item or condition is displayed as one token.

    There is no longer a visual difference between included and excluded items and conditions. They are now differentiated using operators (see Using the filters).

    Footer Toolbar (9)

    The footer bar offers the OK and Cancel buttons.

    Area for Defining Conditions (10)

    In the Define Conditions tab, you can use the following operators to define single and multiple conditions:

    • between
    • equal to
    • contains
    • starts with
    • ends with
    • less than
    • less than or equal to
    • greater than
    • greater than or equal to
    • empty
    • not between
    • not equal to
    • does not contains
    • does not start with
    • does not end with
    • not less than
    • not less than or equal to
    • not greater than
    • not greater than or equal to
    • not empty

    For convenience, the operators are grouped into two categories: Include and Exclude.

    Each condition is displayed as a token in the Selected Items and Conditions tokenizer.

    Information
    The operator dropdown list may not contain all the operators listed above. The type of field value determines which operators are available.
    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.
    Define Conditions - Operators List
    Define Conditions - Operators List

    Behavior and Interaction

    Basic Search and Filters

    • The basic search (mandatory) and filters (optional) are triggered by clicking the Go button. The search results are shown in the result list.
    • If data was already entered in input field from which the user triggered the value help, this data is transferred to the basic search and the results are then filtered accordingly.
    • The basic search performs a search across all fields that are displayed in the filter area and the result list.

    Selecting Items and Defining Conditions

    Depending on your use case, the value help dialog can offer different selection options:

    • Select a single item
    • Define a single condition
    • Select multiple items
    • Define multiple conditions
    • Select multiple items and define multiple conditions

    Users open the value help dialog by clicking the value help icon in 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 dialog. 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 value help dialog for single selection. The icon tab bar and the Selected Items and Conditions 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

    Define a Single Condition (Smartphone)

    Tapping the value help icon opens the Define Condition tab. Users define a condition by choosing the relevant operator and entering the value or values in the corresponding input field(s).

    In this example, we have defined a range.

    Defining a single condition on a smartphone
    Defining a single condition on a smartphone

    Define a Single Condition (Desktop/Tablet)

    Clicking the value help icon opens the Define Condition tab. Users define a condition by choosing the relevant operator and entering the value or values in the corresponding input field(s).

    In this example, we have defined a range.

    Defining a single condition (desktop/tablet)
    Defining a single condition (desktop/tablet)

    Select Multiple Items and Define Multiple Conditions (Smartphone)

    Tapping the value help icon displays the start dialog.

    • The Search and Select tab is used to select multiple items.
    • The Define Conditions tab is used to define multiple conditions.
    • The counters in the titles of both tabs represent the number of selected items/defined conditions.

    All selected items and conditions are added as tokens to the Selected (n) field at the bottom of the start dialog. The counter n indicates the combined number of items selected and conditions defined.

    Start dialog
    Start dialog
    Selecting multiple items on a smartphone
    Selecting multiple items on a smartphone
    Defining multiple conditions (smartphone)
    Defining multiple conditions (smartphone)
    Filters on a smartphone
    Filters on a smartphone

    Select Multiple Items and Define Multiple Conditions (Desktop/Tablet)

    Clicking the value help icon displays the icon tab bar with the Search and Select and Define Conditions tabs.

    • The Search and Select tab is used to select multiple items
    • The Define Conditions tab is used to define multiple conditions.

    All selected items and conditions are added as tokens to the Selected Items and Conditions (n) field at the bottom of the dialog. The counter n indicates the combined number of items selected and conditions defined.

    Selecting multiple items and conditions on a desktop
    Selecting multiple items and conditions on a desktop
    Selecting multiple items and conditions on a desktop
    Selecting multiple items and conditions on a desktop

    Define Multiple Conditions (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 Conditions at the bottom of the start dialog.

    Start dialog
    Start dialog
    Defining multiple conditions on a smartphone
    Defining multiple conditions on a smartphone

    Define Multiple Conditions (Desktop/Tablet)

    Clicking the value help icon opens the Define Conditions tab.

    The selected values are added as tokens to the Selected Conditions at the bottom of the start dialog.

    Defining multiple conditions on a desktop
    Defining multiple conditions on a desktop

    Copying and Pasting Multiple Values

    The area for defining conditions allows the user to enter multiple values at once (copied from the clipboard).

    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, pagination is added to top of the respective area.

    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:

    • Start dialog: [Object] (for example, Company)
    • Search and Select Dialog: Search and Select
    • Filters dialog: Show Filters
    • Define single condition: Define Condition
    • Define multiple conditions: Define Conditions

    For tablet and desktop devices:

    • Selection of multiple items combined with selection of multiple conditions: [Object] (for example, Company)
    • Single item selection: Select: [Object] (for example, Select: Company)
    • Define single condition: Define Condition: [Object] (for example, Define Condition: Company)
    • Define multiple conditions: Define Conditions: [Object] (for example, Define Conditions: Company)

    Filtering

    If necessary, also provide value help for fields offered in the filters. 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.

    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.

    Constant Parameters

    You can use constant parameters to pre-filter suggestion lists, drop-downs, and the value help results list. Users can’t change these parameters.

    Do not show parameters with constant values as filterable fields in the filter bar of the value help dialog or in the result table columns. Constant values should not be visible to users in any way.

    Related Links

    Elements and Controls

    Implementation

    Expandable Text

    The expandable text control provides access to truncated text. A More/Less link shows or hides the full text. You can expand the text inline or display it in a popover, depending on your use case.

    Expandable texts in a table
    Expandable texts in a table

    When to Use

    Use expandable text if:

    • You need to handle long texts or descriptions inside a responsive table, list or form.
    • You need to provide access to truncated text.

    Do not use expandable text if:

    • You need to display text within UI tables (grid table, tree table, analytical table) or the Gantt chart.
    • You can provide short and meaningful alternatives.
    • The content is critical for the user. In this case, use short descriptions that fit into the available space.

    Components

    • Text
    • More/Less link
    • Optional: Popover

    Behavior and Interaction

    Expanding/Collapsing the Text

    Clicking the More link after the truncated text expands the content inline or in a popover, based on the application settings. When the text is fully visible, the More link is replaced by a Less link.

    Clicking the Less link collapses the content again. If a popover is used, it can be closed by clicking Less (1) or clicking anywhere outside the popover (2).

    Inline Text

    Popover

    Responsiveness

    In sizes S, M, L, and XL, the text can be expanded inline or in a popover.

    If you use a popover, the content is displayed in full screen mode on size S.

    Size S – Inline Text

    Expand text with 'More'
    Expand text with 'More'
    Text expanded inline, collapse with 'Less'
    Text expanded inline, collapse with 'Less'

    Size S – Popover

    Expand text with 'More'
    Expand text with 'More'
    Popover text uses full screen, collapse with 'Close'
    Popover text uses full screen, collapse with 'Close'

    Top Tips

    • Adapt the number of characters shown before truncation to fit your use case (default: 100 characters).
    • If using a popover: make sure that the width of the popover always corresponds to the length of the text.
    • If you use the expandable text in a table, set minimal padding to avoid extra white space within the rows.

    Related Links

    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 table, form or other control. One data point is usually displayed by a control, such as a text, object status, or input field. A control can display more than one data point, for example, by concatenating text.

    In contrast to traditional tables, a “cell” of the responsive table is not limited to displaying only one control, and therefore a single cell can present far more than one data point.

    Responsive table
    Responsive table

    Usage

    Use the responsive table if:

    • You need a table. The responsive table is the default table in SAP Fiori.
    • You need to use various controls inside a line item, such as micro charts. By contrast, the analytical table supports only a very limited set of controls.
    • The focus is on line items, not on cells. The responsive table is optimized for viewing complete items on all devices.
    • Selecting one or more items is a main use case and details are needed to choose the correct item.
    • Line items are independent of each other and no operation across columns is needed.
    • You want to have only one implementation for all devices. As the name suggests, the responsive table is responsive.

    Do not use the responsive table if:

    • The main use case is to select one item from a very small number of items, without viewing additional details. In this case, a select or combo box might be more appropriate.
    • The main use case is to select one item from several items, with the possibility of viewing only a few details per item. In this case, a list might be more appropriate. Pay attention to the layout of the list item to ensure that it has a pleasant appearance.
    • The cell level and the spatial relationship between cells is more important than the line item. In this case, use the analytical table or grid table. Examples include spreadsheet analyses and waterfall charts. Note that neither the analytical table nor the grid table are fully responsive. Both are only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You expect the table to contain more than around 1,000 rows. Try using the analytical table or grid table instead; they are easier to handle, perform better, and are optimized for handling large numbers of items.
      Note that neither the analytical table nor the grid table are fully responsive. Both are only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • Comparing items is a major use case. In this case, the analytical table or grid table might be more appropriate because each cell contains only one data point. By contrast, the responsive table offers greater flexibility within line items, including the ability to add more data points per cell and the pop-in function. Both make comparisons more difficult. Note that neither the analytical table nor the grid table are fully responsive. Both are only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • Data needs to be structured in a hierarchical manner. In this case, a tree table might be more appropriate. Although the analytical table can have several grouping levels, it is not as flexible when nodes at several levels contain child nodes. Note that neither the analytical table nor the grid table are fully responsive. Both are only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You need an overview of a large amount of data. In this case, use a chart.
    • You just need it for layout reasons. In this case, use a layout container such as a horizontal layout or a vertical layout instead.
    • You need read-only or editable field-value pairs. In this case, use a form instead. The responsive table is not optimized for form-like input navigation.
    Don't
    Don't use a responsive table as a form
    Don't use a responsive table as a form

    See the table overview to decide which SAP Fiori table is most suitable for your needs.

    Responsiveness

    The responsive table is optimized for viewing one line item at a time with no scrolling or only vertical scrolling, irrespective of the display width.

    On smartphones, only the most important data remains in the one-column or two-column table, while all other data is moved to the space between two item rows, known as the “pop-in area”.

    In this area, data for the corresponding cell is provided as a label/value pair. The label is defined by the column header, and the value is taken from the corresponding cell. Labels can be displayed next to the value or above the value.

    Within the pop-in area, the label/value pairs can be displayed in the following ways (sap.m.Table, property: PopinLayout):

    • Block: Label/value pairs are listed one below the other.
    • GridSmall: Label/value pairs are displayed next to each other in equally spaced grid cells. An additional column is shown for each 13 rem of available width (208 px with default browser settings). If the number of grid cells exceeds the available width, the grid cells wrap. On S size, this layout transforms automatically to a block layout.
    • GridLarge: The display logic is the same as for GridSmall,, but grid columns come with a larger minimum width (26 rem instead of 13 rem).

    In all layouts, you can show the labels next to or above (recommended) the corresponding data.

    The responsive table uses all the available space, and does not provide any padding. If there is space around the table, it comes from the spacing defined for the surrounding layout container.

    Information
    The GridSmall and GridLarge layouts are not available in all browsers. If the chosen layout is not available, it is automatically changed to Block layout.
    Responsive table displayed on a smartphone (size S)
    Responsive table displayed on a smartphone (size S)
    Responsive table displayed on a tablet (size M)
    Responsive table displayed on a tablet (size M)
    Responsive table displayed in compact mode on a desktop computer (size L)
    Responsive table displayed in compact mode on a desktop computer (size L)

    The responsive behavior is optional. If it is not used, the responsive table just minimizes all visible columns until they are no longer readable.

    There are two ways to configure responsiveness: auto pop-in mode and manual pop-in mode (sap.m.Table, property: autoPopinMode).

    The auto pop-in mode ensures responsiveness automatically and is sufficient in most cases. You can still influence the behavior per column, but only to a limited extent.

    The manual mode is more flexible, but needs are more configuration. This configuration becomes more cumbersome when table columns can be shown/hidden or re-ordered. On the other hand, only the manual mode allows you to:

    • Let more than one column stay in the tabular layout
    • Move more than one column into the pop-in area at once

    In both modes, the responsive table ensures that at least one column always remains in the table layout.

    Auto Pop-In Mode

    The auto pop-in mode handles responsiveness automatically. You can optimize this to a certain extent by adapting the behavior per column.

    Columns have a minimum width. As soon as the width of all the visible columns exceeds the table width, the right-most column moves to the pop-in. The default minimum width per column is 8 rem. You can change this value for each column (sap.m.Column, property: autoPopinWidth).

    To further influence the behavior, you can assign columns a priority. Low-priority columns move to the pop-in first (right-most low priority column first), medium-priority columns next, and high-priority columns last. The default priority is “none”, which is handled like the “medium” priority (sap.m.Column, property: importance).

    Instead of moving columns to the pop-in area, you can also hide columns of one or more priority levels (property: hiddenInPopin).

    In auto pop-in mode, all other pop-in-related column settings are ignored.

    Manual Pop-In Mode

    The manual pop-in mode allows more flexibility but also requires more effort if you want it to work in a meaningful way. You also need to invest additional effort if table columns can be shown/hidden or re-ordered.

    You need to configure each column manually. Depending on the width of the table (in pixels), the column needs to know which of the following responses is required:

    • Stay in the table layout (in auto pop-in mode, only one column stays in the table layout).
    • Move to the pop-in (sap.m.Column, with the properties: demandPopin, minScreenWidth, popinHAlign, popinDisplay).
    • Hide

    By default, the table width is assumed to be the screen width. If the table does not use the full width of the screen, app developers must configure the table accordingly (sap.m.Table, property: contextualWidth).

    Because you configure the pop-in response for each column individually, you can also handle more than one column at a given breakpoint. This allows you to move several columns to the pop-in area at once, which isn’t possible in auto pop-in mode

    Each of the three device types has a predefined value for the screen width. However, you will get better results if you offer more breakpoints by using pixel values instead of the predefined values.

    For the smallest screen width, keep the following information in the table layout:

    • The identifier of the line item
    • The key attribute

    Example for Block Layout

    A typical responsive table.

    A typical responsive table
    A typical responsive table

    Hide the information column for a width smaller than 570 px.

    Hiding the information column
    Hiding the information column

    Move the column “vendor” to the pop-in area for a width smaller than 460 px (sap.m.Column, properties: demandPopin, minScreenWidth).

    Moving the vendor column to the pop-in area
    Moving the vendor column to the pop-in area

    Move the column “limit” to the pop-in for a width smaller than 350 px (sap.m.Column, properties: demandPopin, minScreenWidth).

    Moving the limit column to the pop-in area
    Moving the limit column to the pop-in area

    Move the column “price” to the pop-in area for a width smaller than 270 px (sap.m.Column, properties: demandPopin, minScreenWidth).

    Moving the price column to the pop-in area
    Moving the price column to the pop-in area

    If you still need to support smaller screens, values can be moved below the corresponding labels inside the pop-in area. In these examples, this happens for a width smaller than 220 px (sap.m.Column, property: popinDisplay).

    Pop-in area: Moving the data below the labels
    Pop-in area: Moving the data below the labels

    Example for GridLarge Layout

    A more complex responsive table.

    A more complex responsive table (full screen without pop-in)
    A more complex responsive table (full screen without pop-in)

    In this example, the Average Occupancy Rate and Available In columns move to the pop-in area if the screen width is less than 1900 pixels.

    GridLarge layout - 'Average Occupancy Rate' and 'Available In' columns move to the pop-in area
    GridLarge layout - 'Average Occupancy Rate' and 'Available In' columns move to the pop-in area

    If the width is less than 1500 pixels, the Average Stay column moves to the pop-in area.

    GridLarge layout - 'Average Stay' column moves to the pop-in area
    GridLarge layout - 'Average Stay' column moves to the pop-in area

    If the width is less than 1100 pixels, the Description column moves to the pop-in area. Since all four columns in the pop-in area do not fit into one row, the pop-in wraps.

    GridLarge layout - 'Description' column moves to the pop-in area
    GridLarge layout - 'Description' column moves to the pop-in area

    If the width is reduced even further, the Details column moves to the pop-in area. On this narrow screen, only one column fits into one pop-in row, so it looks exactly like the block layout.

    GridLarge layout - 'Details' column moves to the pop-in area
    GridLarge layout - 'Details' column moves to the pop-in area

    Layout

    The optional title bar consists of the title of the responsive table, an item counter, variant management, and the toolbar.

    The filter infobar 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 Add, Edit, and other actions.
    Beneath the toolbar, display a filter infobar (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 infobar 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 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 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. This mode is not recommended (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 (or CTRL+A). Select All should (de)select all items that the user can reach by scrolling.  (sap.m.ListMode.MultiSelect).

    Keyboard: If the focus is on a row, the space bar selects the corresponding item.

    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. (Keyboard: If the focus is on the row itself, the Delete key can be used to trigger the Delete button.)

    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 (keyboard: if the focus is on the row itself, the Enter key triggers navigation). 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 (keyboard: If the focus is on the row itself, the F2 key triggers the Edit button). 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

    For single-selection cases, use the selection mode “single select master”. This is the recommended single-selection mode for master-detail scenarios within the flexible column layout. If you use it there, do not show a “navigated” indicator.

    In rare cases, you can also use the click area for the row for another purpose (for example, to open dialogs). As a result, the click area cannot be used for selecting the row. In these cases only, use the “single select left” selection mode to offer 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 the default delivery.

    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.

    Never disable the selection checkbox. 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.

    Don't
    Single selection left - Don't show radio buttons in the first column in the default delivery
    Single selection left - Don't show radio buttons in the first column in the default delivery
    Don't
    Multiple selection - Don't show checkboxes in the first column in the default delivery
    Multiple selection - Don't show checkboxes in the first column in the default delivery
    Do
    Use the selection mode
    Use the selection mode "single select left" if clicking the row is used for something else (such as navigation)
    Do
    Use the selection mode
    Use the selection mode "single select master" in all other single-selection cases
    Developer Hint
    Select All is only applied to items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded, such as items added via lazy loading with growingScrollToLoad. This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

    To process all items, listen to the selectionChange event and to its selectAll flag. This indicates whether the Select All checkbox was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

    Loading Data

    To indicate that the table is currently loading items, use the busy state. (sap.m.Table, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

    Table in busy state while loading data
    Table in busy state while loading data

    Errors and Warnings

    To indicate that the table contains items with errors or warnings, show a message strip above the table. On the message strip, provide information on errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

    To indicate an error in a single row, see Item States below.

    For details on displaying errors, warnings, and other messages, see Message Handling.

    Developer Hint
    The sap.m.plugins.DataStateIndicator displays a message strip above the table, which shows binding-related messages.
    Table containing errors
    Table containing errors

    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. In doing so, it uses all the available space. We recommend overwriting this default to provide optimal space for your content (sap.m.Column, property: width).

    Especially for tables with just a few columns, we recommend assigning a fixed width to each column and to disabling automatic distribution of the remaining available space (property: fixedLayout, value: Strict). In this case, the rest of the table is filled with an “empty space”.

    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.

    Don't
    Do not distribute just a few columns across the full width
    Do not distribute just a few columns across the full width
    Do
    Use a fixed column width instead
    Use a fixed column width instead

    Column Headers – Best Practices

    Within the column header, provide a label for each column (sap.m.Column, aggregation: header). The column header label is reused as a label in the pop-in area.

    Exception: If the column does not pop in, no column header label is needed as long as at least one column still has a column header label.

    Use controls that wrap and support wrapping with hyphenation, such as text (with wrapping and hyphenation enabled). Do not use controls that truncate.

    Keep column headers sticky.

    Do
    Wrap column headers
    Wrap column headers
    Don't
    Don't truncate column headers
    Don't truncate column headers

    Column headers (sap.m.Column, aggregation: header) usually contain links or text-based controls.

    Column headers can also contain other kinds of SAP Fiori controls. However, the column header cannot be aligned vertically, making it difficult to use many controls in the column header. Using other kinds of controls also creates problems with pop-in behavior and could thus lead to accessibility issues. Therefore, exercise caution when using them in a column header.

    Accepted: Link as column header text (rarely used)
    Accepted: Link as column header text (rarely used)
    Accepted if responsiveness is taken into account: Text plus search field
    Accepted if responsiveness is taken into account: Text plus search field

    If a column cell contains several fields, use an umbrella term in the column header (such as Address for fields like Street, ZIP Code, and City).

    For text and ID fields, use a generic label (for example, Employee for Name and ID).

    If none of these are possible, separate the labels with “/” (for example, Name / Status).

    For boolean values, such as checkboxes, find a descriptive text for the column header.

    Horizontal 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

    Left-align: Text, IDs, phone numbers, URLs, passwords, and email addresses.

    Left-align text
    Left-align text

    Left-align: Status information

    Left-align status information
    Left-align status information

    Right-Align

    Right-align: Dates and times (to ensure comparability for most formats and locales)

    Right-align dates
    Right-align dates

    Right-align: Numbers and amounts, except IDs, to ensure figures are comparable

    Right-align numbers
    Right-align numbers

    Center-Align

    Center-align: Icons, images, and avatars

    Keep the column name for center-aligned columns as short as possible to avoid excessive white space between columns. Alternatively, you can leave the column header empty on the visual UI, and use the invisible text control to provide information on the column content for screen reader listeners.

    Align buttons with the content hierarchically

    Always place buttons directly next to their content. Do not add an additional column for buttons. If you have more than one button, display them next to each other. Order the buttons based on importance. The most important button is on the left, the least important on the right. If there is not enough space to display them all in one line, move the buttons from the right onto the next line one by one. Do not use more than two buttons per line item.

    Vertical Content Alignment

    Top-align where possible to facilitate reading the content on one line.

    Do not use top-alignment if it results in a peculiar layout. This usually happens when controls that need more vertical space are combined with text-only controls, such as input fields. In this case, try center-alignment instead and fine tune it until the layout fits.

    Do
    Use top-alignment where possible
    Use top-alignment where possible
    Don't
    Don't use top alignment if it doesn't make sense
    Don't use top alignment if it doesn't make sense

    Content Formatting

    The responsive table provides flexibility, including multi-line cells, by enabling every control to be put into a cell.

    As a key identifier of an item, use an object identifier. Show the key identifier in the first column. For more information, see object display components.

    If the table width is small, do not hide this column or move it to the pop-in area.

    Object identifier
    Object identifier

    Strings with IDs: If the responsive table contains more single-line data, show the ID in brackets after the corresponding string.

    This minimizes the line height.

    For items with a small line height, place the ID in brackets after the corresponding string
    For items with a small line height, place the ID in brackets after the corresponding string
    If displayed as a link, use the whole text as the link
    If displayed as a link, use the whole text as the link

    Strings with IDs: If line height is already large, show the ID below the corresponding string. Use the object identifier to do so.

    For items with a large line height, place the ID below the corresponding string
    For items with a large line height, place the ID below the corresponding string
    Is displayed as a link, use only the first line as the link
    Is displayed as a link, use only the first line as the link

    If there is more than one key identifier (for example, First Name and Last Name), display these columns first and show the values in bold text.

    Several key identifiers
    Several key identifiers

    For status information, use semantic colors on the foreground elements.

    For status information on text: If the status is actionable, add a transparent icon button next to the text.

    Semantic colors on text
    Semantic colors on text

    Avoid truncation. Use controls that wrap the text and support hyphenation.

    For example, use text.

    Do
    Wrap text
    Wrap text
    Don't
    Don't truncate text
    Don't truncate text

    For editable content, use input fields and other interactive controls within the table cells. If you need to offer edit mode, change your text controls (labels, text, and links, to input fields or other appropriate controls) as soon as you switch to edit mode, but not before.

    You can do this by changing the control or, in more complex cases, by exchanging the whole responsive table.

    Interactive controls – Inline
    Interactive controls – Inline

    If there is no value for a cell, leave it blank. Do not display text as N/A.

    Leave empty fields blank
    Leave empty fields blank

    Numbering Items

    • If the item number has four digits/letters or less and is equally important as the corresponding description, concatenate the item number with the description and show it in one column.
    • If the item number has five digits/letters or more, or if it is more important than the corresponding description, for example, when no description is available, use a separate column for the item number.
    • If the item number is more like an ID in regards to its description, use ID formatting, like Description (ID).
    For short numbers, add the item number to the description
    For short numbers, add the item number to the description

    Flag and Favorite

    Place the flag or favorite marker in the first column (in the default delivery). To change the settings, users need to drill down into the object itself.

    Item marked as a favorite
    Item marked as a favorite

    Empty Tables

    Try not to display an empty responsive table. If there is no way around this, provide instructions on how to fill the table with data (sap.m.Table/ sap.m.ListBase, properties: showNoData, noDataText).

    Examples:

    • If a table is initially empty, provide at least a basic text:
      No items available.
      Overwrite this whenever a hint can be provided on how to fill the table with data.
    • If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
      To start, set the relevant filters.
    • If a table is used together with a filter bar and the filter does not return results, use the following text:
      No data found. Try adjusting the filter settings.

    Adapt the texts above if:

    • The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
    • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of filter settings).

    Remove the item count in the table title if there are zero items.

    Provide meaningful instructions
    Provide meaningful instructions

    Item States

    To show that an item is unread, use the corresponding flag (sap.m.Table, property: showUnread, sap.m.ColumnListItem/ sap.m.ListItemBase, property: unread). This shows most of the content in bold font.

    An unread item
    An unread item

    To show that an item has been modified, for example, within the global edit flow, add the string (Modified) at the bottom of the column that identifies the line item.

    A modified item
    A modified item

    To show that a modified item contains an error (for example, within the global edit flow), add the string (Contains errors) at the bottom of the column that identifies the line item. To do this, use an object status control with the error state (sap.m.ObjectStatus, property: state, value: sap.ui.core.ValueState.Error).

    In addition, highlight the row accordingly (sap.m.ListItemBase, property: highlight).

    A modified item with an error
    A modified item with an error

    To show that an item is locked, use a transparent button with the corresponding icon and the text Locked by [Name] at the bottom of the identifying column. The user can click the button to open a quick view of the person.

    A locked item
    A locked item

    To show that an item is in a draft state, use a transparent-style button with the text Draft at the bottom of the identifying column. The user can click the button to open a popover showing the timestamp of the last change.

    Item in draft state
    Item in draft state

    Show only one state at any one time.

    Highlight Items

    To show that an item needs attention, you can show a highlight indicator next to the item. The highlight indicator can indicate:

    • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
    • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
    • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

    Be aware that the highlight is just an indication. It doesn’t tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

    For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

    (sap.m.ListItemBase, property: highlight)

    Highlighted items using status colors
    Highlighted items using status colors
    Highlighted items using industry-specific (indication) colors
    Highlighted items using industry-specific (indication) colors

    Numbers and Units

    If the following conditions all apply, show the unit of measurement in the column header:

    • The unit of measurement is the same for all rows
    • A single cell contains only one amount with the unit of measurement
    • The column header does not scroll away

    In all other cases, show the unit of measurement together with the corresponding amount within the row.

    Show the unit of measurement in the same column as the corresponding amount.

    For numbers with units, show the correct formatting by using the object number control.

    Object number
    Object number

    For the most important number with its unit, show the correct formatting by using the object number control and the emphasized flag.
    Exception: If all numbers are of equal importance, emphasize none of them.

    If the table width is narrow, do not hide this column or move it to the pop-in area.
    Exception: If the column containing the object identifier and the column containing the key attribute do not fit together on the screen, move the column containing the key attribute to the pop-in area.

    Object number (emphasized)
    Object number (emphasized)

    Drag and Drop

    Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition 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 and provide the corresponding keyboard support. For example, offer (toolbar) buttons for moving or for copying and pasting items. These are keyboard operable and available on all browsers.

    Use drag and drop only in addition to existing visible UI elements
    Use drag and drop only in addition to existing visible UI elements

    If you offer drag and drop for rearranging items within the table, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

    Drop targets in between items
    Drop targets in between items

    Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

    When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on values in a column, the dropped item needs to take on the value of the target group for the corresponding column. If this is not wanted, do not allow users to rearrange items in grouped tables.

    Example:
    A table is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

    Don't
    Don't combine rearranging items with grouping, unless you know exactly what you're doing.
    Don't combine rearranging items with grouping, unless you know exactly what you're doing.

    Context Menu

    Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

    Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

    The context menu can be triggered for the whole table or per row.

    Actions

    To trigger actions on multiple items, use a multiselection table (sap.m.Table, property: mode, value: sap.m.ListMode.MultiSelect), and offer the corresponding actions on the table toolbar. Keep the table toolbar sticky (sap.m.Table, property: sticky).

    Do not offer actions for multiple items if the table is expected to have fewer than 10 items in most cases.

    To trigger actions on a single item only (sap.m.Table, property: mode, value: sap.m.ListMode.SingleSelectMaster):

    • Show the actions on the table toolbar.
    • In rare cases, show the actions within the line item. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. In this case, show the action trigger near the content to which it belongs. Do not add a specific column for actions. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.
    • Don’t bundle inline actions that don’t belong together under an unspecific label, such as Misc, Actions, … , or similar.
    Do
    Inline actions
    Inline actions
    Don't
    Don't combine unrelated inline actions
    Don't combine unrelated 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

    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.

    Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

    There are three options for adding an item. 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.

    Depending on the flow, an item can be in one of three different states:

    • New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
    • Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the table. Ignore current sort, filter and grouping criteria to keep the item visible.
    • Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
      • Inline creation: After Save was triggered on the table toolbar or at page level
      • Create with dialog: A table showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

    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

    Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the first column in the default delivery. Use the primary data point from this column.

    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 infobar below the table title. Clicking the infobar opens the view settings dialog on the filter page.

    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 table toolbar.

    If the infobar is shown, provide an option to reset all corresponding filters on the infobar.

    Keep the infobar sticky (sap.m.Table, property: sticky).

    Developer Hint
    To display the current filter settings on the infobar, 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. Add the shortcut Ctrl+Comma.

    Offer personalization if you need more columns than those that fit on a tablet screen, which is usually five, to fulfill 80% of your main use cases. Before doing so, try to reduce the number of columns, for example, by using several lines per column or by utilizing the pop-in function. See the cheat sheet for an example.

    If all columns are hidden, the table shows a corresponding “no data” text.

    View settings and table personalization icons
    View settings and table personalization icons

    Persist the column layout settings. When a user reopens the app, show the responsive table with the same column layout as last defined by this user.

    Tables in Object Pages

    To show a table in the object page content area, use the responsive table.

    A responsive table with up to 20 expected items can be displayed right away, without lazy loading.
    If you expect the table to have more than 20 items, use one of the following 3 options:

    1. Lazy loading (More button): Use this option if you expect to have up to 100 items.
    2. Tab navigation: If you expect to have more than 50 to 100 items, but less than 400, use the object page with tab navigation instead of anchor navigation. Put the table on a dedicated tab.
    3. Navigation to a list report: If you expect the table to have more than 400 items, or if the tab approach is unsuitable, restrict the number of items in the table itself to a reasonable amount. To provide the user with a way to work with the entire table, offer navigation to a separate list report containing the full table.

    For all of the three options mentioned above, we recommend providing a search, and if feasible, sort and filter capabilities for the table in the object page. Grouping should be avoided.

    For more information on the use of tables within the object page, see the Tables section of the Object Page article.

    Export to Spreadsheet

    On the table toolbar, apps can provide a menu button for exporting table data to a spreadsheet. For the export, use the export to spreadsheet function.

    'Export to Spreadsheet' menu button
    'Export to Spreadsheet' menu button

    Paste

    To paste data from the clipboard to the table, the browser functionality for paste can be used (Ctrl+V or browser context menu).

    • If the focus is on row level, the app has to take the data from the clipboard and add it to the corresponding controls within the table.
    • If the focus is on an editable control within the table, the control gets the data automatically.

    Pasting via context menu does not work if a custom context menu is used.

    Properties

    sap.m.Table

    The following additional properties are available for the responsive table:

    • The property: fixedLayout defines the algorithm the control uses to define column width. Setting it to “false” would perform automatic calculations for the column width, based on the longest non-breakable content. You should always set it to “true” for performance reasons. Exceptions are permissible if the table has only a few columns for a large width and fewer than 10 rows are displayed.
    • The property: backgroundDesign defines the background on which items are rendered. Use the default value.
    • The property: showOverlay provides an overlay on the whole table, which prevents use of the responsive table. This is used within the list report floorplan to mark the table as outdated after filter settings have been changed but the new filter settings have not yet been applied. Do not use it in other cases.
    • The property: inset adds a margin on all sides of the responsive table.
    • The property: headerText is a simple way to set the table title if you just need a title. However, do not use any of the following:
      • A separate toolbar
      • variantManagement
      • headerToolbar aggregation
    • The property: headerDesign affects the appearance of the header if the theme supports it. Leave the default value as it is.
    • The property: footerText adds a small additional row below the table footer or last item. This row can contain text only. Do not use this property.
    • The property: width defines the width of the whole table.
    • The property: includeItemInSelection uses a click on the whole line item to select the corresponding item if the responsive table is in a selection mode. This competes with other settings like “Navigation” or “Active” and should therefore not be used.
    • The property: enableBusyIndicator automatically shows a busy indicator while data is loaded. (In contrast to the property: busy, where the application can control when the table is set to busy state)
    • The property: modeAnimationOn does not have any effect. Do not use it.
    • The property: showSeparators allows you to show all, none, or some separators. The default setting, which is to show all separators, is to be used.
    • The property: swipeDirection allows you to define the direction in which to swipe if additional actions are hidden behind a table row. This works only on touch devices. Do not use this property.
    • The property: rememberSelections leaves items selected even if they are not currently visible, for example, through filtering. If this behavior is not wanted, set the flag to “false”, but you should do so only in exceptional cases.
    • The property: busy sets the table to a busy state. While in busy state, the whole table cannot be used and items cannot be read due to an overlay.
    • The property: busyIndicatorDelay defines the time after which a busy state is shown after the responsive table has been set to this state. Use the default value.
    • The property: visible shows the table (“true”) or hides it (“false”).
    • The property: tooltip does not have an effect. Do not use it.
    • The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). Do not use it.

    sap.m.Column

    The following additional properties are available for sap.m.Column:

    • The property: width defines the width of the column in all units allowed by HTML, such as em, rem, %, and px.
    • The property: styleClass is used if you need to change the visual design of a column. Do not use this, but use the default style instead.
    • The property: visible shows or hides the column.
    • The property: tooltip does not have an effect. Do not use it.

    sap.m.ColumnListItem

    The following additional properties are available for sap.m.ColumnListItem:

    • The property: selected allows an item to be selected programmatically.
    • The property: counter does not have any effect. Do not use it.
    • Do not use the property: busy.
    • Do not use the property: busyIndicatorDelay.
    • The property: visible shows or hides the item.
    • The property: tooltip adds a tooltip to a whole row. The tooltip is only shown on mouse interaction. It will not work on tablets or smartphones. Do not use it.

    Resources

    Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

    Elements and Controls

    Implementation

    List

    In SAP Fiori, we distinguish between tables and lists. Both usually contain homogeneous data, but lists generally have rather basic data, whereas the data in tables tends to be more complex. Lists are mostly used in the master list for a master-detail scenario using the flexible column layout, as well as in popovers or dialogs. For certain use cases, lists can also be used in the dynamic page layout.

    Usage

    Use the list if:

    • You want to display a homogeneous set of basic data.
    • You need to sort, group, or filter simple datasets.
    • You need to display a single-level hierarchy rather than using a complex tree table to support this simple use case.

    Do not use the list if:

    • You want to manage complex datasets that need to be extensively sorted, grouped, filtered, or edited. In this case, use a table.
    • You work with complex hierarchies. In this case, use a tree.

    Responsiveness

    The list is like a layout container. You can change its width, but you must also ensure that the items contained in the list adapt whenever the list is resized.

    All list item variants available in SAP Fiori already adapt to the respective screen size.

    List Item Variants

    The list contains various list items. These items can be of various types depending on the use case and on the content they have. SAPUI5 already provides the most common list items in SAP Fiori in the form of controls, although custom list items can also be created if necessary.

    All the available list item types behave responsively and adapt to changing screen sizes out of the box. Most of them use truncation if size becomes too limited, since they are usually used to navigate to the item details. For custom list items, you can also wrap the texts, if required.

    Object List Item

    The object list item is the list item variant used most frequently in SAP Fiori applications. Consisting of a title, key figure, attributes, and a status, it contains the most important information about an object.

    The space available for the attributes and status is limited as it should only show crucial information that allows the user to decide which items should be dealt with first.

    All essential information about an object is usually provided when the user navigates to the item details.

    For more information, see object list item.

    Object list items
    Object list items

    Standard List Item

    The standard list item is used for less complex entries, such as when the user selects an item in a dialog. This list item contains an optional image, a title, description, and a single info text (which can contain semantic information).

    For more information, see standard list item.

    Standard list items
    Standard list items

    Display List Item

    The display list item is the simplest form of a list item and is only capable of showing a label and values. It is seldom used.

    For more information, see display list item.

    Display list items
    Display list items

    Action List Item

    The action list item allows various actions to be triggered in a dialog. The action list item is not used in the content area.

    For more information, see action list item.

    Action list item
    Action list item

    Feed List Item

    The feed list item is mainly used in feeds and notes.

    For more information, see feed list item.

    Feed with feed list items
    Feed with feed list items

    Input List Item

    The input list item allows the user to enter data in a list item. It is seldom used in SAP Fiori apps as forms are usually the preferable method for entering data.

    For more information, see input list item.

    Input list item
    Input list item

    Components

    The list control comes with the following main properties:

    Header

    The header text contains the title of the list. It is usually only used when the list is in the content area.

    Footer

    The footer text is the last entry in the list, and as such, it scrolls away with the content. Therefore, this property is also seldom used.

    Lazy Loading

    Like the table, the list also allows lazy loading. The “growing” list property is used for this purpose.

    List with header and footer
    List with header and footer

    Empty List

    Avoid empty lists. If necessary, provide instructions on how to fill the list with data (sap.m.List/ sap.m.ListBase, properties: noDataText, showNoData).

    Examples:

    • If a list is initially empty, provide at least a basic text:
      No items available.
      Overwrite this whenever a hint can be provided on how to fill the list with data.
    • If a list is used together with a filter bar (as in the list report), and is initially empty, use the following text:
      No filters set. To start, enter your search and filter settings and run the search.
    • If a list is used together with a filter bar and the filter does not return results, use the following text:
      No items found. Check the search and filter settings.

    Adapt the texts above if:

    • The standard text is not precise enough for your use case (for example, no search is offered, only the search is offered).
    • You are using the live search (no Go button in the filter bar). In this case, leave out “run the search”.
    • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).
    Empty list
    Empty list

    Count

    List items can have a count, which is located on the far right of a row. You can use the count in simple lists, such as those that contain standard list items, to indicate how many subitems the user can expect when navigating to the item.

    Standard list items with counter
    Standard list items with counter

    Read/Unread

    You can set an indicator to highlight unread items, making it easier for the user to discover them (property: showUnread = true). If you set this indicator, all texts for the unread items are shown in bold font.

    By default, this indicator is switched off, and all list items are displayed in normal font.

    Display list item with read and unread items
    Display list item with read and unread items

    Highlight Items

    To show that an item needs attention, a highlight indicator can be shown in front of the item. The highlight indicator can be used to indicate:

    • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
    • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
    • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

    Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

    For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

    (sap.m.ListItemBase, property: highlight)

    Highlighted items using status colors
    Highlighted items using status colors
    Highlighted items using indication colors
    Highlighted items using indication colors

    Behavior and Interaction

    There are several ways to interact with the list and its list items:

    List Level

    Scroll

    The height of the list is defined by the number of items it contains. It does not have its own scroll container, but is scrolled together with the app.

    If the list works in a “growing” mode, it only loads a few items at first. Additional items are only loaded (and rendered) on request. The “request” can either be triggered by scrolling (preferred), or by clicking the More button.

    When the user scrolls, the title and the filter infobar can stick to the top of the surrounding layout container (sap.m.List, property: sticky).

    Information
    The “sticky” feature comes with some limitations:

    • It is not available on all browsers. In non-supporting browsers, the corresponding areas are not fixed on top of the surrounding layout container while scrolling.
    • Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the list is placed within the object page.
    • If the focus is set to a sticky area, the list is automatically scrolled to top.

    Sticky title
    Sticky title

    Mode

    The list can have several modes. The respective property (Mode) allows the following selection methods:

    • None
    • SingleSelectMaster (used to pick one item with no additional indicator, as in the master list for a master-detail scenario with the flexible column layout)
    • SingleSelectLeft (used to pick one item using a radio button on the far left)
    • MultiSelect (used to pick several items from the list using checkboxes on the far left). The Shift key can be used to select a range.
    • Users can (de)select all items using CTRL+A. Select All (de)selects all items that the user can reach by scrolling.
    • Delete (used to delete items from the list using a delete indicator on the far right)
    Guidelines

    • Never disable the selection checkbox. 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.
    • For single-selection master-detail scenarios within the flexible column layout, use the mode “single select master”. Do not 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 this mode only if you really need two different click areas; a small one for a selection, and the rest of the item for something else.
    • If selecting / deselecting all items is important for your app, add a button with the text Select All to the toolbar. Change the button text to Deselect All if all items are selected.

    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.

    Errors and Warnings

    To indicate that the list contains items with errors or warnings, show a message strip above the 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.

    For details on displaying errors, warnings, and other messages, see Message Handling.

    Developer Hint
    The sap.m.plugins.DataStateIndicator displays a message strip above the table, which shows binding-related messages.
    List containing errors
    List containing errors

    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: Add, Collapse All, Expand All, … .

    To trigger a default action on the entire item, use the “Active” or “DetailAndActive” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Active). 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 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 list, with a visual highlight at the beginning of the row.

    Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

    There are three options for adding an item. In order of priority, these are:

    • Add the item inline. Create an empty, editable item as the first item of the list. Show the Save button on the toolbar of the list. This option is recommended for simple scenarios where just a few input fields have to be filled.
    • Open a dialog for items with up to 8 input fields. Save the new item at dialog level.
    • Navigate to a new page. Only use this behavior 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 list.

    Depending on the flow, an item can be in one of three different states:

    • New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
    • Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the list. Ignore current sort, filter and grouping criteria to keep the item visible.
    • Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
      • Inline creation: After Save was triggered on the toolbar or at page level
      • Create with dialog: A list showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

    In the context of draft handling new items are not saved on list level, but rather with the entire draft.

    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 an action which applies to a part of a selection
    Message for an 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 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 and provide the corresponding keyboard support. For example, offer (toolbar) buttons for moving or for copying and pasting items. These are keyboard operable and available for all browsers.

    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

    View Settings

    • Provide individual buttons for each of the following settings on the toolbar of the 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 list accordingly.

    Keep the following in mind:

    • Do not offer any of these features if the 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 list. Use the filter bar instead.
    • Only use the view settings which are really needed. For example, do not offer grouping if it does not support your use case well.
    • Keep the view settings consistent. When a user reopens the app, show the list with the same sort, filter, and group settings as last defined by this user.

    Sort

    • For the default sort setting, 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 located in the filter bar or in a select control placed in the toolbar of the list.
    • If the infobar is shown, provide an option to reset all corresponding filters on the infobar.
    • Keep the infobar sticky (sap.m.List, property: sticky).

    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

    Illustrated Message

    An illustrated message is a recommended combination of a solution-oriented message, engaging illustration, and conversational tone to better communicate an empty state than just a message alone.

    An illustrated message turns a situation (even a negative situation) into a better experience for your users, while ensuring consistency. Through their human-centered approach, illustrated messages help to create a deeper connection with users by making them feel understood, valued, and respected.

    When to Use

    Use an illustrated message if:

    • You want to improve the user experience for one or more empty states or message states in your application.

    Do not use an illustrated message if:

    • You want to use the illustration for decoration, as a simple image, or for something else. If you want to display a person or a product image, use the avatar. If you want to display an image, use the image control.
    • You want to display problem-oriented messages. Reconsider and check out the message handling guidelines and the UI text guidelines for messages.
    Generic illustrated message
    Generic illustrated message

    Components

    An illustrated message consists of the following parts:

    • Illustration set (highly recommended)
    • Message headline (mandatory)
    • Message description (mandatory)
    • Call to action (optional)
    Anatomy of an illustrated message
    Anatomy of an illustrated message

    Illustration Set

    An illustrated message has a set of three UX illustrations per use case: spot, dialog, and scene. Each illustration has a different size and level of detail. The illustrations sizes are used at different breakpoints to ensure that the illustration is always appealing, regardless of the container size.

    The illustrations help clarify the situation and add personality. It’s essential that the illustration is appropriate for the use case and the container you’re using (such as a dialog or card), and that similar use cases are handled consistently. The control automatically comes with illustrations for a set of dedicated use cases (see information box). You can use these illustrations if your use case is the same.

    Each illustration is a themeable SVG file. Illustrations require an alternative text and are generally non-interactive. They do not require a tooltip.

    Illustration set with all three illustration sizes
    Illustration set with all three illustration sizes
    Information
    The following use cases are already covered by the illustrated message control:

    • Before Search
    • No Activities
    • No Data
    • No Email
    • No Entries
    • No Notifications
    • No Saved Items
    • No Search Results
    • No Tasks
    • Unable to Load
    • Unable to Upload

    Check out all use cases in the SAPUI5 samples.

    Headline

    The headline explains the reason for the empty state, preferably in a single line. Use the headline to convey the essence of your message in simple, engaging language.

    Write the headline in sentence case without an ending period (.) or other punctuation. Exceptions include situations where you may want to emphasize the headline with an exclamation mark (!) or question mark (?).

    If you are using one of the standard use cases, you can refine the default text to tailor it to your specific app use case.

    Description

    The description adds details and tells the user what to do next, in three sentences or less. Write the description in sentence case with proper punctuation. You can also set links in the description (property: enableFormattedText).

    If you are using one of the standard use cases, you can refine the default text to tailor it to your specific app use case.

    Call to Action

    If there is a clear next step, include a call to action, ideally in the form of a button.

    Adaptiveness

    Exemplified illustrated message
    Exemplified illustrated message

    Default Behavior

    By default, the illustrated message control adapts its appearance according to the size of the container in which it is placed (such as a dialog or card).

    Fixed Sizes

    Alternatively, you can set a fixed size for the illustrated message. This is only recommended in use cases where a page has multiple empty states in various controls and the illustrated message container is always rather big, resulting in several larger illustrated messages on one screen and hence a lot of unnecessary scrolling. For example, long object pages can contain several UI elements that are all initially empty. Be aware that the illustrated message remains fixed in such cases, also when the user resizes the window.

    The illustrated message control offers the following predefined fixed sizes:

    • Base – This is the smallest size. Be aware that this size does not display an illustration due to lack of space.
    • Spot – This is the normal size for small containers, such as cards.
    • Dialog – This is the size for medium-sized containers, such as dialogs.
    • Scene – This is the size for large controls, such as tables and empty states for an entire screen.
    Base size
    Base size
    Spot size
    Spot size
    Dialog size
    Dialog size
    Scene size
    Scene size

    Examples

    Here are some examples of how illustrated messages can enhance the user experience for different empty states.

    Empty state - No items
    Empty state - No items
    Empty state - No activities
    Empty state - No activities
    Empty state - No tasks
    Empty state - No tasks
    Empty state - No favorites
    Empty state - No favorites
    Empty state - No results, with search
    Empty state - No results, with search
    Empty state - No results
    Empty state - No results

    Top Tips

    Turn a negative event into a positive one

    Take time to design and write a solution-oriented message. Be precise in your wording and be careful with the illustrations!

    Reflect on old message habits. Have a look at the “Don’t” example. Why doesn’t this message work?

    • The image ignores cultural considerations, doesn’t follow the illustration guidelines, and is unlikely to delight the user.
    • The message text is problem-oriented and not helpful. It leaves the user alone with the problem and is likely to trigger negative emotions.

    Ideally, a negative event in a software product doesn’t generate negative emotions. A well-designed illustrated message that leaves users feeling understood and valued can result in a neutral or even positive feeling. Remember that users will benefit from thoughtfully crafted illustrated messages every time they encounter them – perhaps even daily.

    Don't
    Unhelpful, problem-focused message with negative imagery
    Unhelpful, problem-focused message with negative imagery
    Do
    Helpful message with appropriate illustration and possible solutions
    Helpful message with appropriate illustration and possible solutions

    Always write a coherent, solution-oriented message

    Make sure the illustration, message, and call to action work together as one to clarify the situation. Always provide a message. Never use an illustration without a message. A message combined with an illustration is more powerful than a message alone.

    Don't
    Illustration without a message and unrelated to the action
    Illustration without a message and unrelated to the action
    Do
    Matching message, illustration, and action
    Matching message, illustration, and action

    Tailor your message to your use case

    • Always ensure that the default text fits in the context. If not, replace it or make it more precise.
      Example:
      Default text: No results found / Try changing your search criteria.
      Adapted text (supplier table used with a filter bar): No suppliers found / Try adjusting your filter settings.
    • Recommended: Replace generic terms like “data” and “object” with your specific business object.
      Example:
      Default text: There’s no data yet / When there is you’ll see it here.
      Adapted text: There are no orders yet / When there are, you’ll see them here.

    Additional tips

    • Never use other icons, images, or illustrations for an illustrated message. Always follow the guidelines on using UX illustrations.
    • Don’t use the predefined illustrations for other use cases than the ones they were designed for. This would dilute the strength and recognizability of the illustration in the defined use case.
    • Set alternative texts for the illustrations.

    Related Links

    Elements and Controls

    Implementation

    Illustrated Message

    An illustrated message is a recommended combination of a solution-oriented message, engaging illustration, and conversational tone to better communicate an empty state than just a message alone.

    An illustrated message turns a situation (even a negative situation) into a better experience for your users, while ensuring consistency. Through their human-centered approach, illustrated messages help to create a deeper connection with users by making them feel understood, valued, and respected.

    When to Use

    Use an illustrated message if:

    • You want to improve the user experience for one or more empty states or message states in your application.

    Do not use an illustrated message if:

    • You want to use the illustration for decoration, as a simple image, or for something else. If you want to display a person or a product image, use the avatar. If you want to display an image, use the image control.
    • You want to display problem-oriented messages. Reconsider and check out the message handling guidelines and the UI text guidelines for messages.
    Generic illustrated message
    Generic illustrated message

    Components

    An illustrated message consists of the following parts:

    • Illustration set (highly recommended)
    • Message headline (mandatory)
    • Message description (mandatory)
    • Call to action (optional)
    Anatomy of an illustrated message
    Anatomy of an illustrated message

    Illustration Set

    An illustrated message has a set of three UX illustrations per use case: spot, dialog, and scene. Each illustration has a different size and level of detail. The illustrations sizes are used at different breakpoints to ensure that the illustration is always appealing, regardless of the container size.

    The illustrations help clarify the situation and add personality. It’s essential that the illustration is appropriate for the use case and the container you’re using (such as a dialog or card), and that similar use cases are handled consistently. The control automatically comes with illustrations for a set of dedicated use cases (see information box). You can use these illustrations if your use case is the same.

    Each illustration is a themeable SVG file. Illustrations require an alternative text and are generally non-interactive. They do not require a tooltip.

    Illustration set with all three illustration sizes
    Illustration set with all three illustration sizes
    Information
    The following use cases are already covered by the illustrated message control:

    • Before Search
    • No Activities
    • No Data
    • No Email
    • No Entries
    • No Notifications
    • No Saved Items
    • No Search Results
    • No Tasks
    • Unable to Load
    • Unable to Upload

    Check out all use cases in the SAPUI5 samples.

    Headline

    The headline explains the reason for the empty state, preferably in a single line. Use the headline to convey the essence of your message in simple, engaging language.

    Write the headline in sentence case without an ending period (.) or other punctuation. Exceptions include situations where you may want to emphasize the headline with an exclamation mark (!) or question mark (?).

    Description

    The description adds details and tells the user what to do next, in three sentences or less. Write the description in sentence case with proper punctuation. You can also set links in the description (property: enableFormattedText).

    Call to Action

    If there is a clear next step, include a call to action, ideally in the form of a button.

    Adaptiveness

    Exemplified illustrated message
    Exemplified illustrated message

    Default Behavior

    By default, the illustrated message control adapts its appearance according to the size of the container in which it is placed (such as a dialog or card).

    Fixed Sizes

    Alternatively, you can set a fixed size for the illustrated message. This is only recommended in use cases where a page has multiple empty states in various controls and the illustrated message container is always rather big, resulting in several larger illustrated messages on one screen and hence a lot of unnecessary scrolling. For example, long object pages can contain several UI elements that are all initially empty. Be aware that the illustrated message remains fixed in such cases, also when the user resizes the window.

    The illustrated message control offers the following predefined fixed sizes:

    • Base – This is the smallest size. Be aware that this size does not display an illustration due to lack of space.
    • Spot – This is the normal size for small containers, such as cards.
    • Dialog – This is the size for medium-sized containers, such as dialogs.
    • Scene – This is the size for large controls, such as tables and empty states for an entire screen.
    Base size
    Base size
    Spot size
    Spot size
    Dialog size
    Dialog size
    Scene size
    Scene size

    Examples

    Here are some examples of how illustrated messages can enhance the user experience for different empty states.

    Empty state - No items
    Empty state - No items
    Empty state - No activities
    Empty state - No activities
    Empty state - No tasks
    Empty state - No tasks
    Empty state - No favorites
    Empty state - No favorites
    Empty state - No results, with search
    Empty state - No results, with search
    Empty state - No results
    Empty state - No results

    Top Tips

    Turn a negative event into a positive one

    Take time to design and write a solution-oriented message. Be precise in your wording and be careful with the illustrations!

    Reflect on old message habits. Have a look at the “Don’t” example. Why doesn’t this message work?

    • The image ignores cultural considerations, doesn’t follow the illustration guidelines, and is unlikely to delight the user.
    • The message text is problem-oriented and not helpful. It leaves the user alone with the problem and is likely to trigger negative emotions.

    Ideally, a negative event in a software product doesn’t generate negative emotions. A well-designed illustrated message that leaves users feeling understood and valued can result in a neutral or even positive feeling. Remember that users will benefit from thoughtfully crafted illustrated messages every time they encounter them – perhaps even daily.

    Don't
    Unhelpful, problem-focused message with negative imagery
    Unhelpful, problem-focused message with negative imagery
    Do
    Helpful message with appropriate illustration and possible solutions
    Helpful message with appropriate illustration and possible solutions

    Always write a coherent, solution-oriented message

    Make sure the illustration, message, and call to action work together as one to clarify the situation. Always provide a message. Never use an illustration without a message. A message combined with an illustration is more powerful than a message alone.

    Don't
    Illustration without a message and unrelated to the action
    Illustration without a message and unrelated to the action
    Do
    Matching message, illustration, and action
    Matching message, illustration, and action

    Additional tips

    • Never use other icons, images, or illustrations for an illustrated message. Always follow the guidelines on using UX illustrations.
    • Don’t use the predefined illustrations for other use cases than the ones they were designed for. This would dilute the strength and recognizability of the illustration in the defined use case.
    • Set alternative texts for the illustrations.

    Related Links

    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 table, form or other control. One data point is usually displayed by a control, such as a text, object status, or input field. A control can display more than one data point, for example, by concatenating text.

    In contrast to traditional tables, a “cell” of the responsive table is not limited to displaying only one control, and therefore a single cell can present far more than one data point.

    Responsive table
    Responsive table

    Usage

    Use the responsive table if:

    • You need a table. The responsive table is the default table in SAP Fiori.
    • You need to use various controls inside a line item, such as micro charts. By contrast, the analytical table supports only a very limited set of controls.
    • The focus is on line items, not on cells. The responsive table is optimized for viewing complete items on all devices.
    • Selecting one or more items is a main use case and details are needed to choose the correct item.
    • Line items are independent of each other and no operation across columns is needed.
    • You want to have only one implementation for all devices. As the name suggests, the responsive table is responsive.

    Do not use the responsive table if:

    • The main use case is to select one item from a very small number of items, without viewing additional details. In this case, a select or combo box might be more appropriate.
    • The main use case is to select one item from several items, with the possibility of viewing only a few details per item. In this case, a list might be more appropriate. Pay attention to the layout of the list item to ensure that it has a pleasant appearance.
    • The cell level and the spatial relationship between cells is more important than the line item. In this case, use the analytical table or grid table. Examples include spreadsheet analyses and waterfall charts. Note that neither the analytical table nor the grid table are fully responsive. Both are only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You expect the table to contain more than around 1,000 rows. Try using the analytical table or grid table instead; they are easier to handle, perform better, and are optimized for handling large numbers of items.
      Note that neither the analytical table nor the grid table are fully responsive. Both are only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • Comparing items is a major use case. In this case, the analytical table or grid table might be more appropriate because each cell contains only one data point. By contrast, the responsive table offers greater flexibility within line items, including the ability to add more data points per cell and the pop-in function. Both make comparisons more difficult. Note that neither the analytical table nor the grid table are fully responsive. Both are only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • Data needs to be structured in a hierarchical manner. In this case, a tree table might be more appropriate. Although the analytical table can have several grouping levels, it is not as flexible when nodes at several levels contain child nodes. Note that neither the analytical table nor the grid table are fully responsive. Both are only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
    • You need an overview of a large amount of data. In this case, use a chart.
    • You just need it for layout reasons. In this case, use a layout container such as a horizontal layout or a vertical layout instead.
    • You need read-only or editable field-value pairs. In this case, use a form instead. The responsive table is not optimized for form-like input navigation.
    Don't
    Don't use a responsive table as a form
    Don't use a responsive table as a form

    See the table overview to decide which SAP Fiori table is most suitable for your needs.

    Responsiveness

    The responsive table is optimized for viewing one line item at a time with no scrolling or only vertical scrolling, irrespective of the display width.

    On smartphones, only the most important data remains in the one-column or two-column table, while all other data is moved to the space between two item rows, known as the “pop-in area”.

    In this area, data for the corresponding cell is provided as a label/value pair. The label is defined by the column header, and the value is taken from the corresponding cell. Labels can be displayed next to the value or above the value.

    Within the pop-in area, the label/value pairs can be displayed in the following ways (sap.m.Table, property: PopinLayout):

    • Block: Label/value pairs are listed one below the other.
    • GridSmall: Label/value pairs are displayed next to each other in equally spaced grid cells. An additional column is shown for each 13 rem of available width (208 px with default browser settings). If the number of grid cells exceeds the available width, the grid cells wrap. On S size, this layout transforms automatically to a block layout.
    • GridLarge: The display logic is the same as for GridSmall,, but grid columns come with a larger minimum width (26 rem instead of 13 rem).

    In all layouts, you can show the labels next to or above (recommended) the corresponding data.

    The responsive table uses all the available space, and does not provide any padding. If there is space around the table, it comes from the spacing defined for the surrounding layout container.

    Information
    The GridSmall and GridLarge layouts are not available in all browsers. If the chosen layout is not available, it is automatically changed to Block layout.
    Responsive table displayed on a smartphone (size S)
    Responsive table displayed on a smartphone (size S)
    Responsive table displayed on a tablet (size M)
    Responsive table displayed on a tablet (size M)
    Responsive table displayed in compact mode on a desktop computer (size L)
    Responsive table displayed in compact mode on a desktop computer (size L)

    The responsive behavior is optional. If it is not used, the responsive table just minimizes all visible columns until they are no longer readable.

    There are two ways to configure responsiveness: auto pop-in mode and manual pop-in mode (sap.m.Table, property: autoPopinMode).

    The auto pop-in mode ensures responsiveness automatically and is sufficient in most cases. You can still influence the behavior per column, but only to a limited extent.

    The manual mode is more flexible, but needs are more configuration. This configuration becomes more cumbersome when table columns can be shown/hidden or re-ordered. On the other hand, only the manual mode allows you to:

    • Let more than one column stay in the tabular layout
    • Move more than one column into the pop-in area at once

    In both modes, the responsive table ensures that at least one column always remains in the table layout.

    Auto Pop-In Mode

    The auto pop-in mode handles responsiveness automatically. You can optimize this to a certain extent by adapting the behavior per column.

    Columns have a minimum width. As soon as the width of all the visible columns exceeds the table width, the right-most column moves to the pop-in. The default minimum width per column is 8 rem. You can change this value for each column (sap.m.Column, property: autoPopinWidth).

    To further influence the behavior, you can assign columns a priority. Low-priority columns move to the pop-in first (right-most low priority column first), medium-priority columns next, and high-priority columns last. The default priority is “none”, which is handled like the “medium” priority (sap.m.Column, property: importance).

    Instead of moving columns to the pop-in area, you can also hide columns of one or more priority levels (property: hiddenInPopin).

    In auto pop-in mode, all other pop-in-related column settings are ignored.

    Manual Pop-In Mode

    The manual pop-in mode allows more flexibility but also requires more effort if you want it to work in a meaningful way. You also need to invest additional effort if table columns can be shown/hidden or re-ordered.

    You need to configure each column manually. Depending on the width of the table (in pixels), the column needs to know which of the following responses is required:

    • Stay in the table layout (in auto pop-in mode, only one column stays in the table layout).
    • Move to the pop-in (sap.m.Column, with the properties: demandPopin, minScreenWidth, popinHAlign, popinDisplay).
    • Hide

    By default, the table width is assumed to be the screen width. If the table does not use the full width of the screen, app developers must configure the table accordingly (sap.m.Table, property: contextualWidth).

    Because you configure the pop-in response for each column individually, you can also handle more than one column at a given breakpoint. This allows you to move several columns to the pop-in area at once, which isn’t possible in auto pop-in mode

    Each of the three device types has a predefined value for the screen width. However, you will get better results if you offer more breakpoints by using pixel values instead of the predefined values.

    For the smallest screen width, keep the following information in the table layout:

    • The identifier of the line item
    • The key attribute

    Example for Block Layout

    A typical responsive table.

    A typical responsive table
    A typical responsive table

    Hide the information column for a width smaller than 570 px.

    Hiding the information column
    Hiding the information column

    Move the column “vendor” to the pop-in area for a width smaller than 460 px (sap.m.Column, properties: demandPopin, minScreenWidth).

    Moving the vendor column to the pop-in area
    Moving the vendor column to the pop-in area

    Move the column “limit” to the pop-in for a width smaller than 350 px (sap.m.Column, properties: demandPopin, minScreenWidth).

    Moving the limit column to the pop-in area
    Moving the limit column to the pop-in area

    Move the column “price” to the pop-in area for a width smaller than 270 px (sap.m.Column, properties: demandPopin, minScreenWidth).

    Moving the price column to the pop-in area
    Moving the price column to the pop-in area

    If you still need to support smaller screens, values can be moved below the corresponding labels inside the pop-in area. In these examples, this happens for a width smaller than 220 px (sap.m.Column, property: popinDisplay).

    Pop-in area: Moving the data below the labels
    Pop-in area: Moving the data below the labels

    Example for GridLarge Layout

    A more complex responsive table.

    A more complex responsive table (full screen without pop-in)
    A more complex responsive table (full screen without pop-in)

    In this example, the Average Occupancy Rate and Available In columns move to the pop-in area if the screen width is less than 1900 pixels.

    GridLarge layout - 'Average Occupancy Rate' and 'Available In' columns move to the pop-in area
    GridLarge layout - 'Average Occupancy Rate' and 'Available In' columns move to the pop-in area

    If the width is less than 1500 pixels, the Average Stay column moves to the pop-in area.

    GridLarge layout - 'Average Stay' column moves to the pop-in area
    GridLarge layout - 'Average Stay' column moves to the pop-in area

    If the width is less than 1100 pixels, the Description column moves to the pop-in area. Since all four columns in the pop-in area do not fit into one row, the pop-in wraps.

    GridLarge layout - 'Description' column moves to the pop-in area
    GridLarge layout - 'Description' column moves to the pop-in area

    If the width is reduced even further, the Details column moves to the pop-in area. On this narrow screen, only one column fits into one pop-in row, so it looks exactly like the block layout.

    GridLarge layout - 'Details' column moves to the pop-in area
    GridLarge layout - 'Details' column moves to the pop-in area

    Layout

    The optional title bar consists of the title of the responsive table, an item counter, variant management, and the toolbar.

    The filter infobar 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 Add, Edit, and other actions.
    Beneath the toolbar, display a filter infobar (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 infobar 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 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 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. This mode is not recommended (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).

    Keyboard: If the focus is on a row, the space bar selects the corresponding item.

    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. (Keyboard: If the focus is on the row itself, the Delete key can be used to trigger the Delete button.)

    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 (keyboard: if the focus is on the row itself, the Enter key triggers navigation). 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 (keyboard: If the focus is on the row itself, the F2 key triggers the Edit button). 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

    For single-selection cases, use the selection mode “single select master”. This is the recommended single-selection mode for master-detail scenarios within the flexible column layout. If you use it there, do not show a “navigated” indicator.

    In rare cases, you can also use the click area for the row for another purpose (for example, to open dialogs). As a result, the click area cannot be used for selecting the row. In these cases only, use the “single select left” selection mode to offer 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 the default delivery.

    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.

    Never disable the selection checkbox. 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.

    Don't
    Single selection left - Don't show radio buttons in the first column in the default delivery
    Single selection left - Don't show radio buttons in the first column in the default delivery
    Don't
    Multiple selection - Don't show checkboxes in the first column in the default delivery
    Multiple selection - Don't show checkboxes in the first column in the default delivery
    Do
    Use the selection mode
    Use the selection mode "single select left" if clicking the row is used for something else (such as navigation)
    Do
    Use the selection mode
    Use the selection mode "single select master" in all other single-selection cases
    Developer Hint
    Select All is only applied to items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded, such as items added via lazy loading with growingScrollToLoad. This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

    To process all items, listen to the selectionChange event and to its selectAll flag. This indicates whether the Select All checkbox was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

    Loading Data

    To indicate that the table is currently loading items, use the busy state. (sap.m.Table, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

    Table in busy state while loading data
    Table in busy state while loading data

    Errors and Warnings

    To indicate that the table contains items with errors or warnings, show a corresponding message strip above the table. On the message strip, provide information on the current number of errors and/or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

    To indicate an error in a single row, see Item States below.

    For details on displaying errors, warnings, and other messages, see Message Handling.

    Developer Hint
    The sap.m.plugins.DataStateIndicator displays a message strip above the table, which shows binding-related messages.
    Table containing errors and warnings
    Table containing errors and warnings

    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. In doing so, it uses all the available space. We recommend overwriting this default to provide optimal space for your content (sap.m.Column, property: width).

    Especially for tables with just a few columns, we recommend assigning a fixed width to each column and to disabling automatic distribution of the remaining available space (property: fixedLayout, value: Strict). In this case, the rest of the table is filled with an “empty space”.

    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.

    Don't
    Do not distribute just a few columns across the full width
    Do not distribute just a few columns across the full width
    Do
    Use a fixed column width instead
    Use a fixed column width instead

    Column Headers – Best Practices

    Within the column header, provide a label for each column (sap.m.Column, aggregation: header). The column header label is reused as a label in the pop-in area.

    Exception: If the column does not pop in, no column header label is needed as long as at least one column still has a column header label.

    Use controls that wrap and support wrapping with hyphenation, such as text (with wrapping and hyphenation enabled). Do not use controls that truncate.

    Keep column headers sticky.

    Do
    Wrap column headers
    Wrap column headers
    Don't
    Don't truncate column headers
    Don't truncate column headers

    Column headers (sap.m.Column, aggregation: header) usually contain links or text-based controls.

    Column headers can also contain other kinds of SAP Fiori controls. However, the column header cannot be aligned vertically, making it difficult to use many controls in the column header. Using other kinds of controls also creates problems with pop-in behavior and could thus lead to accessibility issues. Therefore, exercise caution when using them in a column header.

    Accepted: Link as column header text (rarely used)
    Accepted: Link as column header text (rarely used)
    Accepted if responsiveness is taken into account: Text plus search field
    Accepted if responsiveness is taken into account: Text plus search field

    If a column cell contains several fields, use an umbrella term in the column header (such as Address for fields like Street, ZIP Code, and City).

    For text and ID fields, use a generic label (for example, Employee for Name and ID).

    If none of these are possible, separate the labels with “/” (for example, Name / Status).

    For boolean values, such as checkboxes, find a descriptive text for the column header.

    Horizontal 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

    Left-align: Text, IDs, phone numbers, URLs, passwords, and email addresses.

    Left-align text
    Left-align text

    Left-align: Status information

    Left-align status information
    Left-align status information

    Right-Align

    Right-align: Dates and times (to ensure comparability for most formats and locales)

    Right-align dates
    Right-align dates

    Right-align: Numbers and amounts, except IDs, to ensure figures are comparable

    Right-align numbers
    Right-align numbers

    Center-Align

    Center-align: Icons, images, and avatars

    Keep the column name for center-aligned columns as short as possible to avoid excessive white space between columns. Alternatively, you can leave the column header empty on the visual UI, and use the invisible text control to provide information on the column content for screen reader listeners.

    Responsive table with an avatar and an action
    Responsive table with an avatar and an action

    Center-align: All actions in a line item that appear as buttons

    If you have more than one action, display them next to each other. Order the buttons based on importance. The most important action is on the left, the least important on the right. If there is not enough space to display them all in one line, move the actions from the right onto the next line one by one. We recommend a maximum of two buttons per line item.

    Responsive table with icon, avatar, and actions
    Responsive table with icon, avatar, and actions

    Vertical Content Alignment

    Top-align where possible to facilitate reading the content on one line.

    Do not use top-alignment if it results in a peculiar layout. This usually happens when controls that need more vertical space are combined with text-only controls, such as input fields. In this case, try center-alignment instead and fine tune it until the layout fits.

    Do
    Use top-alignment where possible
    Use top-alignment where possible
    Don't
    Don't use top alignment if it doesn't make sense
    Don't use top alignment if it doesn't make sense

    Content Formatting

    The responsive table provides flexibility, including multi-line cells, by enabling every control to be put into a cell.

    As a key identifier of an item, use an object identifier. Show the key identifier in the first column. For more information, see object display components.

    If the table width is small, do not hide this column or move it to the pop-in area.

    Object identifier
    Object identifier

    Strings with IDs: If the responsive table contains more single-line data, show the ID in brackets after the corresponding string.

    This minimizes the line height.

    For items with a small line height, place the ID in brackets after the corresponding string
    For items with a small line height, place the ID in brackets after the corresponding string
    If displayed as a link, use the whole text as the link
    If displayed as a link, use the whole text as the link

    Strings with IDs: If line height is already large, show the ID below the corresponding string. Use the object identifier to do so.

    For items with a large line height, place the ID below the corresponding string
    For items with a large line height, place the ID below the corresponding string
    Is displayed as a link, use only the first line as the link
    Is displayed as a link, use only the first line as the link

    If there is more than one key identifier (for example, First Name and Last Name), display these columns first and show the values in bold text.

    Several key identifiers
    Several key identifiers

    For status information, use semantic colors on the foreground elements.

    For status information on text: If the status is actionable, add a transparent icon button next to the text.

    Semantic colors on text
    Semantic colors on text

    Avoid truncation. Use controls that wrap the text and support hyphenation.

    For example, use text.

    Do
    Wrap text
    Wrap text
    Don't
    Don't truncate text
    Don't truncate text

    For editable content, use input fields and other interactive controls within the table cells. If you need to offer edit mode, change your text controls (labels, text, and links, to input fields or other appropriate controls) as soon as you switch to edit mode, but not before.

    You can do this by changing the control or, in more complex cases, by exchanging the whole responsive table.

    Interactive controls – Inline
    Interactive controls – Inline

    If there is no value for a cell, leave it blank. Do not display text as N/A.

    Leave empty fields blank
    Leave empty fields blank

    Numbering Items

    • If the item number has four digits/letters or less and is equally important as the corresponding description, concatenate the item number with the description and show it in one column.
    • If the item number has five digits/letters or more, or if it is more important than the corresponding description, for example, when no description is available, use a separate column for the item number.
    • If the item number is more like an ID in regards to its description, use ID formatting, like Description (ID).
    For short numbers, add the item number to the description
    For short numbers, add the item number to the description

    Flag and Favorite

    Place the flag or favorite marker in the first column (in the default delivery). To change the settings, users need to drill down into the object itself.

    Item marked as a favorite
    Item marked as a favorite

    Empty Tables

    Try not to display an empty responsive table. If there is no way around this, provide instructions on how to fill the table with data (sap.m.Table/ sap.m.ListBase, properties: showNoData, noDataText).

    Examples:

    • If a table is initially empty, provide at least a basic text:
      No items available.
      Overwrite this whenever a hint can be provided on how to fill the table with data.
    • If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
      To start, set the relevant filters.
    • If a table is used together with a filter bar and the filter does not return results, use the following text:
      No data found. Try adjusting the filter settings.

    Adapt the texts above if:

    • The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
    • The standard text is misleading (for example, if the data is filled based on a master-detail pattern instead of filter settings).

    Remove the item count in the table title if there are zero items.

    Provide meaningful instructions
    Provide meaningful instructions

    Item States

    To show that an item is unread, use the corresponding flag (sap.m.Table, property: showUnread, sap.m.ColumnListItem/ sap.m.ListItemBase, property: unread). This shows most of the content in bold font.

    An unread item
    An unread item

    To show that an item has been modified, for example, within the global edit flow, add the string (Modified) at the bottom of the column that identifies the line item.

    A modified item
    A modified item

    To show that a modified item contains an error (for example, within the global edit flow), add the string (Contains errors) at the bottom of the column that identifies the line item. To do this, use an object status control with the error state (sap.m.ObjectStatus, property: state, value: sap.ui.core.ValueState.Error).

    In addition, highlight the row accordingly (sap.m.ListItemBase, property: highlight).

    A modified item with an error
    A modified item with an error

    To show that an item is locked, use a transparent button with the corresponding icon and the text Locked by [Name] at the bottom of the identifying column. The user can click the button to open a quick view of the person.

    A locked item
    A locked item

    To show that an item is in a draft state, use a transparent-style button with the text Draft at the bottom of the identifying column. The user can click the button to open a popover showing the timestamp of the last change.

    Item in draft state
    Item in draft state

    Show only one state at any one time.

    Highlight Items

    To show that an item needs attention, you can show a highlight indicator next to the item. The highlight indicator can indicate:

    • A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
    • Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
    • Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

    Be aware that the highlight is just an indication. It doesn’t tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

    For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

    (sap.m.ListItemBase, property: highlight)

    Highlighted items using status colors
    Highlighted items using status colors
    Highlighted items using industry-specific (indication) colors
    Highlighted items using industry-specific (indication) colors

    Numbers and Units

    If the following conditions all apply, show the unit of measurement in the column header:

    • The unit of measurement is the same for all rows
    • A single cell contains only one amount with the unit of measurement
    • The column header does not scroll away

    In all other cases, show the unit of measurement together with the corresponding amount within the row.

    Show the unit of measurement in the same column as the corresponding amount.

    For numbers with units, show the correct formatting by using the object number control.

    Object number
    Object number

    For the most important number with its unit, show the correct formatting by using the object number control and the emphasized flag.
    Exception: If all numbers are of equal importance, emphasize none of them.

    If the table width is narrow, do not hide this column or move it to the pop-in area.
    Exception: If the column containing the object identifier and the column containing the key attribute do not fit together on the screen, move the column containing the key attribute to the pop-in area.

    Object number (emphasized)
    Object number (emphasized)

    Drag and Drop

    Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition 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 and provide the corresponding keyboard support. For example, offer (toolbar) buttons for moving or for copying and pasting items.

    Use drag and drop only in addition to existing visible UI elements
    Use drag and drop only in addition to existing visible UI elements

    If you offer drag and drop for rearranging items within the table, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

    Drop targets in between items
    Drop targets in between items

    Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

    When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on values in a column, the dropped item needs to take on the value of the target group for the corresponding column. If this is not wanted, do not allow users to rearrange items in grouped tables.

    Example:
    A table is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

    Don't
    Don't combine rearranging items with grouping, unless you know exactly what you're doing.
    Don't combine rearranging items with grouping, unless you know exactly what you're doing.

    Context Menu

    Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

    Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

    The context menu can be triggered for the whole table or per row.

    Actions

    To trigger actions on multiple items, use a multiselection table (sap.m.Table, property: mode, value: sap.m.ListMode.MultiSelect), and offer the corresponding actions on the table toolbar. Keep the table toolbar sticky (sap.m.Table, property: sticky).

    Do not offer actions for multiple items if the table is expected to have fewer than 10 items in most cases.

    To trigger actions on a single item only (sap.m.Table, property: mode, value: sap.m.ListMode.SingleSelectMaster):

    • 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.
    • Don’t bundle inline actions that don’t belong together under an unspecific label, such as Misc, Actions, … , or similar.
    Do
    Inline actions
    Inline actions
    Don't
    Don't combine unrelated inline actions
    Don't combine unrelated 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.

    Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

    There are three options for adding an item. 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.

    Depending on the flow, an item can be in one of three different states:

    • New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator.
    • Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the table. Ignore current sort, filter and grouping criteria to keep the item visible.
    • Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
      • Inline creation: After Save was triggered on the table toolbar or at page level
      • Create with dialog: A table showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

    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

    Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the first column in the default delivery. Use the primary data point from this column.

    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 infobar below the table title. Clicking the infobar opens the view settings dialog on the filter page.

    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 table toolbar.

    If the infobar is shown, provide an option to reset all corresponding filters on the infobar.

    Keep the infobar sticky (sap.m.Table, property: sticky).

    Developer Hint
    To display the current filter settings on the infobar, 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. Add the shortcut Ctrl+Comma.

    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

    Smart Form

    The smart form control creates a form. If used with smart fields, the smart form provides both read-only and editable views, and OData annotations for the smart fields are taken into account. The smart form also provides a toolbar with a title.

    When to Use

    Use the smart form if:

    • You use an OData service for your app (OData version 2 only).
    • You are using only (or primarily) smart fields inside your form. In this case, the smart form is faster to implement.

    Do not use the smart form if:

    Components

    The smart form consists of a toolbar and a form.

    Toolbar

    The following options are provided:

    1. Expand/collapse button
    2. Title
    3. App-specific actions

    Expand/Collapse Button

    The expand/collapse button is optional (properties: expandable,
    expanded). It shows or hides the form.

    Expanded smart form
    Expanded smart form
    Collapsed smart form
    Collapsed smart form
    Guidelines

    • Do not use the expand/collapse button in object pages.
    • Even in other places, it is not usually recommended.

    Title

    The title is optional (property: title).

    App-Specific Actions

    App-specific actions can only be added using a custom toolbar (aggregation: customToolbar).

    Guidelines
    For custom actions, follow the guidelines for object handling.
    Developer Hint
    The smart form can add its title to the custom toolbar.

    Form

    The form consists of form groups (sap.ui.comp.smartform.Group) and a layout.

    Form Groups

    Each form group comes with:

    • A title
    • One or several form elements and/or semantic form elements

    Form elements (sap.ui.comp.smartform.GroupElement) consist of a label and one or several UI elements. If smart fields are used, the label is automatically provided by the corresponding metadata. If more than one smart field is used, define which label to display (GroupElement, property: elementForLabel).

    The semantic form element (sap.ui.comp.smartform.SemanticGroupSlement) provides additional support when more than one control is attached to a single label. In display mode, the corresponding texts are displayed as a single value and therefore use less space. You can define a delimiter, which is shown between the fields.

    A semantic form element in edit mode
    A semantic form element in edit mode
    The same semantic form element in display mode
    The same semantic form element in display mode
    Guidelines
    When using more than one control in a form element, consider the semantic form element. In most cases, it will be the better choice.
    Developer Hint

    • Ideally, use only smart fields.
    • If this is not possible, use only controls that implement theIFormContent interface . Other controls could damage the visual layout, keyboard support, and screen reader support.

    Layout

    The layout defines how the form groups and form elements are placed on the screen, depending on the available width (aggregation: layout). There are two layout options: column layout and responsive grid layout.

    Guidelines

    Behavior and Interaction

    Display and Edit Mode

    In display mode, the line height for each row is reduced (property: editable). This results in less white space between two lines of text. This setting is passed to all smart fields inside the smart form, which then also switch automatically.

    Developer Hint
    Controls other than the smart field need to be adapted manually.

    Validation

    The smart form offers two validation modes: standard and asynchronous (property: validationMode). The standard validation mode works only for smart fields and only with synchronous validation.

    Developer Hint
    Always use the asynchronous mode: it works for all form elements, not only for smart fields.

    Responsiveness

    The smart form acts exactly like the embedded controls. For details, see:

    Size S
    Size S
    Size M
    Size M
    Size L
    Size L
    Size XL
    Size XL

    Example

    Smart form in edit mode
    Smart form in edit mode
    The same smart form in display mode
    The same smart form in display mode

    Top Tips

    Properties

    The following properties are available for sap.ui.comp.smartform.SmartForm:

    • The property: checkButton adds a button labeled Check to the toolbar. The button triggers front-end validation on available smart fields. Do not use it. Follow the guidelines for form field validation instead.
    • The property: editToggable adds an icon-only button to the toolbar, which switches the editable property. Do not use it. Follow the guidelines for object handling instead.
    • The property: entityType is used for key user adaptations.
    • The property: flexEnabled is used for key user adaptations.
    • The property: horizontalLayoutGroupElementMinWidth only works with the horizontal layout, which is deprecated. Do not use it. Use the column layout instead.
    • The property: ignoredFields is used for key user adaptations.
    • The property: importance hides all smart fields with lower importance. Do not use it.
    • The property: useHorizontalLayout only works with the horizontal layout, which is deprecated. Use the column layout instead.

    The following properties are available for sap.ui.comp.smartform.Group:

    • The property: horizontalLayoutGroupElementMinWidth only works with the horizontal layout, which is deprecated. Use the column layout instead.
    • The property: label is deprecated. Use the aggregation: title instead.
    • The property: useHorizontalLayout only works with the horizontal layout, which is deprecated. Use the column layout instead.
    • The aggregation: layout is deprecated. Use the aggregation: layoutData instead.

    Related Links

    Elements and Controls

    Implementation

    Invisible Message

    The invisible message control provides a hidden message that can be used by assistive technologies, such as screen readers. Invisible messages provide information to users when the visible screen content changes dynamically (for example, when a page is refreshed).

    When to Use

    Use the invisible message if:

    • You need to offer accessibility support to communicate dynamic changes on the interface that are visually perceptible.
    • You need to provide a message for screen reader users independently of the focus position.

    Do not use the invisible message if:

    • You want to provide static and visible, but non-focusable information for users of assistive technologies. Use the invisible text instead.
    • You want to provide additional information for users of assistive technologies that is not available for sighted users. While you should not discriminate users of assistive technologies, you should also not give them “privileges” .
    • You want to hide information. It might still be available for users of assistive technologies.
    • You want to hide long texts. The information is probably important enough to be shown! Furthermore, short texts are far more convenient, even for users of assistive technologies.

    Examples

    The examples below show typical use cases for invisible messages.

    Information
    Invisible messages may also be provided by the framework as an intrinsic part of the control. If no message is provided out of the box, you must create one.

    Search

    • Indicate when a results list is rendered following a search.
    • Indicate the number of hits found.
    • Provide a short hint on how to get to the result list.

    Navigation within Dialogs

    Indicate when the entire content of a dialog changes. Provide accessibility support for navigation in a dialog.

    Dialog navigation - List
    Dialog navigation - List
    Dialog navigation - Details
    Dialog navigation - Details

    Saving

    Indicate when the page or a form has been saved in apps with or without draft handling.

    'Draft saved' indicator
    'Draft saved' indicator

    Auto-Update

    Use an invisible message to indicate:

    • When a has been refreshed
    • When data on the page has been updated automatically
    • When an entry in an input field has been corrected automatically

    Deletion

    Provide a success message when an item has been deleted. Refer to the UI text guidelines for message toasts.

    Dynamic Messaging

    Indicate when a message strip has appeared automatically and provide its content.

    Information message strip
    Information message strip

    Dynamic Change in a Control

    Indicate when a user action has changed the appearance of a control (for example, if pressing a button changes the button text or icon tooltip).

    Toggle button with label change
    Toggle button with label change

    Top Tips

    • Provide short and meaningful texts.
    • Avoid mentioning system or configuration details.

    Related Links

    Elements and Controls

    Implementation

    Form / Simple Form

    Information
    This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

    For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

    Intro

    A form is used to present data to the user and to allow users to enter data in a structured way.

    The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

    In SAPUI5, forms can be built using two different controls:

    With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

    The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

    • The layout and structure are defined by the content that is entered.
    • Form containers and form elements are created automatically according to the content type.
    • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
    • All other controls following this label will be assigned to its row (form element).

    Types

    There are three types of forms:

    • Display-only: the data is presented only as label-value field pairs without editable fields.
    • Editable: the data is presented as label-input field pairs, so users can enter data.
    • Mixed: some fields are editable and some are not.
    Form control in display- only mode
    Form control in display- only mode
    Form in edit mode
    Form in edit mode
    Developer Hint
    The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
    Information
    Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

    Responsiveness

    The default settings of the control are not ideal for all possible use cases. Instead, applications can use one of the various layouts for the S, M, L and XL sizes.

    Column Layout

    The  ColumnLayout control renders a form group in a column-based responsive way. Depending on its size, the group is divided into one or more columns.

    • XL – max. 4 columns
    • L – max. 3 columns
    • M – max. 2 columns
    • S – 1 column

    To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns. The group elements are spread out into columns, depending on the number of group elements and their size.

    Example:

    • 4 columns and 2 groups: each group will use 2 columns.
    • 3 columns and 2 groups: the larger one will use 2 columns, the smaller one 1 column.

    The size of a group element will be determined by the number of visible elements assigned to it. If there are more groups than columns, every group uses only one column. So the last row of the form control will not be fully used. This will result in white space.

    The form elements are spread out to the columns of a group arranged in a newspaper-like order. The position of the labels and fields depends on the size of the used column. If there is enough space, the labels are next to the fields, otherwise above the fields.

    If you use the default form settings, each form group is displayed in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right side of the screen.

     

    The examples show how forms with one and two form groups are displayed with and without layout balancing.

    One form group with default arrangement
    One form group with default arrangement
    One form group with balanced column layout
    One form group with balanced column layout
    Two form groups with default arrangement
    Two form groups with default arrangement
    Two form groups with balanced column layout
    Two form groups with balanced column layout

    Responsive Grid Layout

    The responsive grid layout is a form using a responsive grid. Depending on the available space, the groups are rendered in one or multiple columns, and the labels are rendered in the same row as the fields or above the fields. This behavior can be influenced by the properties of this layout control.

    By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

    Note: For downward compatibility reasons, the default form layout control for the form and simple form is the column layout, not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

    Breakpoints

    Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

    Form with breakpointM – Size S
    Form with breakpointM – Size S
    Form with breakpointM – Size M
    Form with breakpointM – Size M

    The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

    Form with breakpointL – Size M
    Form with breakpointL – Size M
    Form with breakpointL – Size L
    Form with breakpointL – Size L

    Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

    Form with breakpointXL – Size L
    Form with breakpointXL – Size L
    Form with breakpointXL – Size XL
    Form with breakpointXL – Size XL

    In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

    Padding of a container
    Padding of a container
    Developer Hint
    To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

    Label-Field Ratio

    For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

    The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

    We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

    Form with a label-field ratio of 3:5:4
    Form with a label-field ratio of 3:5:4
    Developer Hint
    To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

    Otherwise..

    • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
    • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
    • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

    Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

    Size S (Smartphones and Dialogs)

    The form and simple form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

    The label-field ratio is 12:12:0 by default:

    • 12 grid columns of the responsive grid layout are used by the labels.
      (A label handles the space of a whole row.)
    • 12 grid columns of the responsive grid layout are used by the fields.
      (A field handles the space of a whole row.)
    • 0 grid columns of the responsive grid layout are used by empty columns.
      (There is no empty space on the right of the field.)
    Form in size S
    Form in size S

    Size M

    Size M of the form and simple form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

    The label-field ratio is 2:10:0 by default:

    • 2 grid columns of the responsive grid layout are used by the labels.
    • 10 grid columns of the responsive grid layout are used by the fields.
    • 0 columns of the responsive grid layout are used by empty columns.

    Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

    Form in size M
    Form in size M

    Size L

    The form and simple form in size L use a two-column layout within the responsive grid layout by default. That means that the form groups are placed next to each other to have all the information on one screen and to avoid scrolling. In these columns, the labels are positioned in the same row as the corresponding input field or value. So the form groups adopt the Z layout (reading direction in rows, not in columns).

    The label-field ratio is 4:8:0 by default:

    • 4 grid columns of the responsive grid layout are used by the labels.
    • 8 grid columns of the responsive grid layout are used by fields.
    • 0 grid columns of the responsive grid layout are used by empty columns.
    Form in size L
    Form in size L

    Size XL

    Like the form and the simple form in size L, the size XL uses also a two-column layout within the responsive grid layout by default. To have all the information on one screen and avoid scrolling, the form groups are placed next to each other.  In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

    The label-field ratio for size XL is 4:8:0 (technically the value is set to -1 and inherits the value of size L, see also the development hint below) by default:

    • 4 grid columns of the responsive grid layout are used by labels.
    • 8 grid columns of the responsive grid layout are used by fields.
    • 0 grid columns of the responsive grid layout are used by empty columns.
    Form in size XL
    Form in size XL
    Developer Hint
    For forms and simple forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

    Layout

    One Page, One Form

    If a form contains only one group, do not use a group title – instead, use the form title.

    Form with only one group (form title)
    Form with only one group (form title)

    If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

    One form with several groups (no form title)
    One form with several groups (no form title)

    If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

    A form as one of several elements on a page (form title)
    A form as one of several elements on a page (form title)

    One Page, Many Forms

    If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

    Several forms on a page (emphasized groups)
    Several forms on a page (emphasized groups)
    Forms with several groups
    Forms with several groups

    Various Layouts

    The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

    Size S (Smartphones and Dialogs)

    Retain the default behavior (single column layout with a label-field ratio 12:12:0).

    Form in size S (12:12:0)
    Form in size S (12:12:0)

    Size M (Tablet) – Full Screen

    If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

    Form in a split screen – Size M (4:7:1)
    Form in a split screen – Size M (4:7:1)

    If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

    Form in full screen – Size M (3:5:4)
    Form in full screen – Size M (3:5:4)

    As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

    Form with long labels and fields – Size M (4:8:0)
    Form with long labels and fields – Size M (4:8:0)

    If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

    Form with several form groups (two columns) – Size M (12:12:0)
    Form with several form groups (two columns) – Size M (12:12:0)
    Developer Hint
    Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

    Size L (Desktop Screens)

    If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

    Form with a single form group (one column) – Size L (3:5:4)
    Form with a single form group (one column) – Size L (3:5:4)

    If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

    Form with several form groups (two columns) – Size L (12:12:0)
    Form with several form groups (two columns) – Size L (12:12:0)
    Developer Hint
    Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

    Size XL (Desktop Wide Screens)

    If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

    Form with a single form group (one column) – Size XL (3:5:4)
    Form with a single form group (one column) – Size XL (3:5:4)

    The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

    Form with an empty column – Size XL (4:8:0)
    Form with an empty column – Size XL (4:8:0)

    If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

    Form with single group in a column layout - Size XL - (12:12:0)
    Form with single group in a column layout - Size XL - (12:12:0)

    If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

    Form with multiple form groups (two columns) – Size XL (4:8:0)
    Form with multiple form groups (two columns) – Size XL (4:8:0)

    If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

    Form with two form groups (three columns) – Size XL (12:12:0)
    Form with two form groups (three columns) – Size XL (12:12:0)
    Form with three form groups (three columns) – Size XL (12:12:0)
    Form with three form groups (three columns) – Size XL (12:12:0)

    If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

    Form with a lot of white space (two columns)
    Form with a lot of white space (two columns)
    Form with less white space (single-column layout)
    Form with less white space (single-column layout)
    Developer Hint
    Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

    Components

    The following UI elements can be placed in the form container:

    Guidelines

    • Order the form logically from a user’s perspective. For example, ask for a user’s name before asking them for their address.
    • Group related information by using form and group titles.
    • Use Column layout instead of Responsive Grid layout, if possible.
    • Try to arrange form groups (especially in size L and XL) in a way that the form:
      • Is easy to read and understand.
      • Does not contain too much white space (split groups if necessary).
    • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
    • If the form field doesn’t have a value, add an empty state indicator in the display-only mode. This is not a default property, so you will have to add it specifically.
    • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
    • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

    Label

    To avoid truncation, labels within forms wrap automatically.

    Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is to make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

    • A label is not a help text. Give each field a meaningful label. Make labels succinct, short and descriptive.
    • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property, and the asterisk will be inserted automatically.
    • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the style sheet. Do not write the colon manually in the label text.
    • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)

    Label Alignment

    • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
    • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
    Information
    The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

    Unit of Measurement

    You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

    If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

    Unit of Measurement
    Unit of Measurement

    Amount Alignment

    When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

    When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

    Data Loss Message

    Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

    Form Field Validation

    Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

    Field validation and validation report
    Field validation and validation report

    Input Assistance

    Intelligent systems can help users by recommending appropriate content or suggesting an action or input the user may “prefer”. The system assists the user by entering data or filtering data. Typical examples might be a search phrase suggestion, an appropriate form template, or a set of suggested default values for certain fields, based on the user input and interaction history.

    For more information, see Designing Intelligent Systems – Input Assistance.

    Error Prevention

    Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

    Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

    Placeholder

    Provide a placeholder (or input prompt) as a short hint (a word or short phrase) to help the user with data entry. A hint can be a sample value or a brief description of the expected format.

    Avoid using the placeholder attribute as an alternative to a label. This is important because the placeholder text is overwritten as soon as the form is filled out. Labels are necessary to indicate the meaning of the form fields when the placeholders are no longer visible.

    Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

    Toolbar

    The form supports actions on form toolbar level as well as on group header level. Application development teams can add actions such as ‘Edit’, ‘Save’ or ‘Cancel’. If there is an action that only applies to the specific group on group level, it can only be added on the group header level of the specific group.

    Expanded/ Collapsed Form

    The form supports expand / collapse buttons on a per-group level. However, we recommend avoiding the usage of expand / collapse behavior on a form.

    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 List

    You can use the smart list control to create lists or trees.

    Smart list as list
    Smart list as list
    Smart list as tree
    Smart list as tree
    Information
    Unlike most smart controls, the smart list does not use annotations to create the content automatically.

    When to Use

    You can use the smart list if you use an OData service for your app (OData version 2 only).

    For detailed recommendations on when to use a list or a tree, see the corresponding guideline articles:

    Components

    The smart list control consists of an overflow toolbar (1) in combination with either the list control (2) or the tree control (3).

    Smart list used as a list:

    (1) An overflow toolbar on the top
    (2) List control below

    List components
    List components

    Smart list used as a tree:

    (1) An overflow toolbar on the top
    (3) Tree control below

    Tree components
    Tree components

    Behavior and Interaction

    The individual controls mentioned in the Components section behave exactly as they would on their own.

    For more information, see the respective guidelines:

    Responsiveness

    Both smart list variants are responsive. Each embedded control behaves as specified.

    The following schematic examples show how list and tree use cases appear on different devices.

    Responsive list - Size S
    Responsive list - Size S
    Responsive list - Size M
    Responsive list - Size M
    Responsive list - Size L
    Responsive list - Size L
    Responsive tree - Size S
    Responsive tree - Size S
    Responsive tree - Size M
    Responsive tree - Size M
    Responsive tree - Size L
    Responsive tree - Size L

    For more information, see the respective guidelines:

    Top Tips

    List or tree? What you should consider

    Due to their one-dimensional layout, lists are much easier for users to grasp than trees. First consider if you can use a list to present your data. Only use a tree if your data requires a hierarchy. Make sure that the nodes are clearly labeled and that information is not nested too deeply.

    Developer Hint
    The listType property controls whether the smart list presents itself as a list or tree. It must be appended by either List or Tree to work.

    More guidelines and tips for each component of the smart list

    • Guidelines and tips for toolbars
    • Guidelines and tips for lists
    • Guidelines and tips for trees

    Related Links

    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 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.

    The 1 Month view has an additional style for half-column appointment distribution, which is mainly used to avoid overlapping. The property appointmentRoundWidth can be set to “HalfColumn” or “None” (default). Currently, the width of the appointment is always rounded to 12 hours.
    Note: This property is also applied when the calendar interval type is Days and the view shows more than 20 days.

    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.

    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 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.

    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 four types of appointments:

    • Regular: Displayed in two rows. One-row display is also possible if the appointmentsReducedHeight property is set to “true”.
    • Half-size: Always displayed in one row, shows the title.
    • Large: Always displayed in three rows, also shows the description for each appointment (if available).
    • Automatic: The number of rows is determined automatically.
      Appointment Info Rows
      Title only 1 row
      Title + text
      or:
      Title + description      		 2 rows
      Title + text + description 3 rows

    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.

    Guidelines
    Ensure that colors are used consistently within your product area.

    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.

    Select control in place of the title

    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

    Quick View

    The quick view is similar to a popover, but has a predefined structure, a fixed set of UI elements, and automatic UI rendering.

    Usage

    Use the quick view if:

    • You want to display a concise overview of an object.
    • You want to display information about, for example, an employee or a company.
    • You can split your information into groups (for example, contact details and company information).

    Do not use the quick view if:

    • You want to provide information in a way other than displaying it in groups.
    • You want to display complex information about an object.

    Responsiveness

    The quick view is based on the popover. It therefore inherits the same basic properties from it and provides the same responsiveness. For more information, see popover.

    Layout

    Generic Quick View

    The figure on the right shows how the content is structured within the quick view. At the top of the content area, you can display an image next to the title and subtitle. Additionally, groups and fields are used to structure the information.

    You can use the fallbackIcon property to define a backup icon. This icon is displayed if the initial image or icon is can’t be loaded.

    Example of a generic quick view
    Example of a generic quick view

    Quick View Examples

    You can create your own quick view element or, as with the two examples below show, there are also basic structures for displaying employee and company information in a quick view.

    Example: Employee quick view
    Example: Employee quick view
    Example: Company quick view
    Example: Company quick view

    Behavior and Interaction

    The quick view is based on the popover. It therefore inherits the same basic properties from it and provides the same interaction. For more information, see popover.

    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

    Invisible Text

    The invisible text control provides a simple hidden text that can be used by assistive technologies such as screen readers to provide contextual information.

    When to Use

    Use invisible text if:

    • You need to make contextual information that is visible for sighted users available to users of assistive technologies, such as screen readers.
    • You need to provide contextual information specifically for users of assistive technologies (not required by sighted users).

    Do not use invisible text if:

    • You want to provide additional information for users of assistive technologies that is not available for sighted users. While you should not discriminate users of assistive technologies, you should also not give them “privileges” .
    • You want to hide information. It might still be available for users of assistive technologies.
    • You want to hide long texts. The information is probably important enough to be shown! Furthermore, short texts are far more convenient, even for users of assistive technologies.

    Examples

    Here are some examples of use cases that require invisible texts:

    • A title that sighted users don’t need (for example, a title for a form or table).
    • A form row with more than one form element: Use the concatenated label for sighted users and single invisible texts for users of assistive technologies.
    A form with two fields in one row
    A form with two fields in one row
    A group of radio buttons without a visible label
    A group of radio buttons without a visible label
    • A visual element without any kind of label, such as a busy indicator animation.
    Animation for loading
    Animation for loading
    • Information about uncommon states or properties, such as semantic states.
    Buttons use the invisible text control to announce their type
    Buttons use the invisible text control to announce their type

    Properties

    The properties busy, busyIndicatorDelay, and visible have no effect. Do not use them.

    Top Tips

    • Provide short and meaningful texts. Adhere to the text guidelines for labels.
    • Do not use an invisible text as a replacement for a label (property: text).
    Developer Hint
    It is not sufficient to just add the invisible text control. You must also assign it to the corresponding control. Unlike labels, invisible texts are not assigned automatically in forms.

    To assign the invisible text to a control, add the ID of the invisible text to the ariaLabelledBy association of the corresponding control.

    Related Links

    Elements and Controls

    Implementation

    UI Elements

    This article provides an overview of the UI elements used in SAP Fiori. UI elements range from simple controls to complex controls, and include reuse components, smart controls, and controls designed specifically for assistive technologies.
    • Simple controls are the very basic UI elements, such as buttons or links.
    • Complex controls themselves use other controls. For example, a toolbar contains buttons and a smart table contains a title, a toolbar, and items.
    • Reuse components were originally built for a specific use case and line of business. If you have a similar scenario, you may also be able to use them for your app.
    • Smart controls offer additional features to the standard SAPUI5 features, such as OData metadata support. That’s why they are typically used with SAP Fiori elements. However, smart controls can also be used for regular freestyle apps.
    • Controls to support assistive technologies are needed to make the interface accessible to everyone, including people with disabilities.

    Quick Access

    The list below provides an overview of our UI element categories and the UI elements you can expect to find in each one. For tips on when and how to use specific elements, also check the When to Use section under UI Elements in the navigation structure. To get a visual overview of all UI elements, check out the Explore page.


    Action / Navigation

    Action Sheet

    Breadcrumb

    Button

    Icon Tab Bar

    Link

    Smart Link

    Collaboration

    Group Feed Component

    Timeline

    Data Visualization

    3D Viewport

    Analytical Card

    Chart (VizFrame)

    Gantt Chart

    Interactive Chart

    Map

    Micro Chart

    Micro Process Flow

    Network Graph

    Process Flow

    Status Indicator

    Timeline

    Dialog / Popover

    Dialog

    Message Box

    Select Dialog

    Table Select Dialog

    Popover

    Quick View


    Display 

    Avatar

    Avatar Group

    Carousel

    Currency

    Expandable Text

    Formatted Text

    Generic Tag

    HTML

    Image

    Info Bar

    Label

    Lightbox

    Object Display Components

    Progress Indicator

    Status Indicator

    T Account

    Text

    Title

    Token

    Filter

    Contextual Filter

    Filter Bar

    Info Bar

    Token

    Visual Filter Bar

    Variant Management

    Form / Layout / Container

    Carousel

    Dynamic Side Content

    Flexible Grid

    Form / Simple Form

    Icon Tab Bar

    Panel

    Scroll Container

    Smart Form


    Loading / Processing

    Busy Dialog

    Busy Indicator

    Busy State

    Messaging

    Illustrated Message

    Message Box

    Message Page

    Message Popover

    Message Strip

    Message Toast

    Message View

    Table / List / Tree

    Analytical Table (ALV)

    Grid Table

    Responsive Table

    Smart Table

    Tree Table

    Table Personalization

    Grid List

    List

    Smart List

    Tree

    Toolbar

    Chart Toolbar

    Footer Toolbar

    Header Toolbar

    Table Toolbar

    Tree Toolbar


    User Input (Fields, Combo Boxes)

    Input Field

    Multi-Input Field

    Combo Box

    Multi-Combo Box

    Select

    Mask Input

    User Input (Dialog, Visual)

    Select Dialog

    Table Select Dialog

    Value Help Dialog

    Checkbox

    Radio Button

    Rating Indicator

    Slider

    Range Slider

    Step Input

    Switch

    User Input (Date, Time, Calendar)

    Date Picker

    Time Picker

    Date/Time Picker

    Date Range Selection

    Dynamic Date

    Calendar Date Interval

    Calendar

    Planning Calender

    Single Planning Calendar

    User Input (Colors, Texts, Files)

    Color Palette

    Color Palette Popover

    Feed and Notes

    Rich Text Editor

    Search

    Text Area

    Upload Set


    Support for Assistive Technologies

    Invisible Message

    Invisible Text

    Smart Controls

    Dynamic Date

    Smart Field

    Smart Filter Bar

    Smart Form

    Smart Link

    Smart List

    Smart Table

    Reuse Components

    Calculation Builder

    PDF Viewer

    Smart Table

    Intro

    The smart table creates a responsive table, grid table, tree table, or analytical table based on an OData (Open Data Protocol) service and its annotations. The table toolbar comes with additional built-in features, such as personalization, export to spreadsheet, and variant management.

    When to Use

    Use the smart table if:

    • You use an OData service for your app (OData version 2 only).
    • The feature set of the smart table fits for your app. In this case, the smart table is faster to implement.
    • You need more than one of the major features of the smart table. Otherwise, you might not benefit from a shorter implementation time. For example, if you just need the export to spreadsheet feature, creating a responsive table directly is usually faster than using the smart table.

    Do not use the smart table if:

    • You use a different technology to OData version 2. Use the corresponding table control directly.
    • You need more flexibility in the content design, such as several different row templates or less complex personalization features. Use the responsive table directly.
    • You do not have complex data. Another control like a select, combo box, list, grid list, tree, or smart list might do the job better.
    • You have very complex data. Did you check the chart?
    • Users need to switch between a chart and table. The smart table is not designed to work inside an existing chart container. In this case, use either the smart chart or the corresponding table directly.
    • You need to layout different controls in a table-like grid. Use a flexible grid instead.
    • You need to layout different input fields with labels. Use a form, simple form, or smart form.

    Components

    The smart table consists of a table toolbar (1), an infobar (2), and a table (3).

    The components of a smart table
    The components of a smart table

    Table Toolbar

    Toolbar with all features provided by the smart table out-of-the-box
    Toolbar with all features provided by the smart table out-of-the-box

    The table toolbar is generated automatically. The following toolbar content is provided by the smart table out-of-the box:

    1. Title
    2. Item counter
    3. Variant management
    4. Show Details / Hide Details
    5. View Settings
    6. Export to Spreadsheet
    7. Maximize / Minimize

    In addition, you can add app-specific actions.

    Title

    The title is optional (property: header).

    Guidelines
    Add a title whenever the title is not indicated in the surrounding area.
    Developer Hint
    If you don’t provide a title, ensure that you support screen reader users: create a simple table in the XML view, use ariaLabelledBy to point to the corresponding text, and add this table to the smart table. Make sure that the table type within the smart table is set accordingly. The smart table will take care of the rest (creating columns, and so on).

    Item Counter

    The item counter is optional and only available if you show a title (property: showRowCount).

    Guidelines
    Show the item counter together with the table title, unless:

    Variant Management

    Variant management is optional (properties: persistencyKey, useVariantManagement, currentVariantID, association: smartVariant).

    Guidelines
    Use variant management only if really needed.

    Show Details / Hide Details

    Show Details / Hide Details is mandatory with and only available for the responsive table. Columns with a low priority (low or medium priority on phones) are hidden in the pop-in area (properties: demandPopin, showDetailsButton, annotation: UI.Importance). You can define which column priority levels are hidden (property: detailsButtonSettings). The button only appears if there are corresponding columns in the pop-in area.

    Details hidden
    Details hidden
    Details shown
    Details shown

    View Settings

    View Settings are optional. The button triggers a P13n Dialog (property: useTablePersonalisation). The View Settings dialog can also be opened with the shortcut Ctrl+Comma.

    Guidelines
    Offer view settings only if they are really needed. Tables with just a few columns and rows do not need to be sorted, filtered, or grouped.

    Sort and Filter

    Sorting, filtering, and column settings are automatically available for all columns in all tables. For single columns, you can remove the sort and filter settings (annotations: SortRestrictions, FilterRestrictions).

    • The current sort state and sort order is displayed as an icon in the column header of the sorted columns.
    • The current filter state is displayed as follows:
      • In the responsive table, an infobar is shown if filters have been set in the table personalization settings.
      • For all other tables, filtering is indicated by an icon in the column header of each filtered column.

    When amounts with different currencies appear in a single column, you can change the sort behavior to sort these columns first by currency, then by amount (annotation: ApplyMulitUnitBehaviorForSortingAndFiltering). This behavior is applied for all such columns in the smart table. It cannot be defined per column.

    Guidelines

    • Do not turn off the info bar (property: useInfoBar).
    • In the default delivery, sort items in a meaningful order. This works only for the grid table, tree table, and analytical table. You can also provide default filter settings (all tables) and grouping (responsive table and analytical table only) (annotation:
      PresentationVariant).
    • If the smart table is used together with a filter bar (property:
      smartFilterId), do not offer filtering for the smart table itself.

    Developer Hint
    The smart table can be linked to a smart filter bar. If linked, the filter bar settings are automatically applied to the smart table (sap.ui.comp.smarttable,SmartTable, property: smartFilterId).

    Group

    Group settings are only available for the responsive table (all columns, one level only) and the analytical table (dimension columns only, multiple levels).

    The following text is usually shown on the group header:
    [Label of the grouped column]: [Grouping value]

    Within the analytical table, the grouped column remains visible by default if it is grouped using the P13n Dialog. The column is hidden if it is grouped using the column header menu.

    Guidelines
    In some cases, the group header text may not be shown automatically as described. This applies to special cases in the analytical table (for example, if the displayed text is not taken directly from the data source), as well as custom columns in both responsive and analytical tables. In such cases, you must set and format the group header text yourself.

    Column Settings

    Column settings are used to show and hide columns. For the grid table, tree table, and analytical table, the column settings automatically enable resizing via the column header and size-to-fit for text-only columns (double-click on column separator line).

    Guidelines
    If sorting, grouping, and/or filtering are needed, also show the column settings (sap.ui.comp.smarttable.SmartTable, property: useTablePersonalisation).
    Developer Hint
    Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

    Export to Spreadsheet

    Export to Spreadsheet is optional. The button triggers either a front-end export using the export to spreadsheet utility, or a back-end export via Gateway (properties: useExportToExcel, exportType). The front-end export allows for additional settings and can also be triggered with the shortcut Ctrl+Shift+E.

    Guidelines

    • Only offer the Export to Spreadsheet option if your end users typically export the data shown in the table 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, tables with only a few items, shopping carts, or data that does not need to be analyzed.
    • If you offer the Export to Spreadsheet button, use the front-end export.
    • If your table has columns with non-textual content, provide a textual equivalent for those columns. Non-textual content is not exported.

    Warning
    With both methods, the file size is limited by the available browser memory. As a result, exporting large tables can lead to memory overflows and crash the export process.

    Apply the following size restrictions as a rule-of-thumb:

    • For the front-end export, do not export more than 2 million table cells on desktop browsers or 100,000 table cells on tablets and phones.
    • For the back-end export, do not export more than 100,000 table cells.

    For larger tables, consider using custom-built, specialized export solutions instead.

    Maximize / Minimize

    Maximize / Minimize is optional. It allows users to show the table in full screen mode and to exit full screen mode (property: showFullScreenButton).

    Guidelines

    App-Specific Actions

    App-specific actions can only be added using a custom toolbar (aggregation: customToolbar).

    Developer Hint

    Infobar

    Infobar with filter information
    Infobar with filter information

    The infobar is only available for the responsive table. It indicates which filter settings are currently active. If no filters are set, the infobar is hidden (property: useInfoToolbar, value: Auto).

    Guidelines

    Table

    A responsive table within a smart table
    A responsive table within a smart table

    The table is generated automatically. The sections below describe the behavior and different possibilities:

    Table

    The table provides the following features:

    Guidelines

    • Use the responsive table wherever possible. Use the other table types only if really needed. If you use another table, provide a fallback solution for phones.
    • For the responsive table, the smart table initially loads 20 items and shows a More button for loading additional items. Change this behavior if:
      • You expect fewer than 200 items. Load all items from the start (sap.m.Table, property: growing).
      • You expect more than 200 items. Adapt the number of items initially loaded to cater for large screens, and load additional items automatically when the user scrolls down (sap.m.Table, property: growingScrolllToLoad).

    Developer Hint
    To change the growing behavior, create a responsive table with just the settings for the growing behavior, and hand it over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on).
    Developer Hint

    • The property tableBindingPath defines the path from which the data is fetched.
    • The property enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

    Developer Hint
    To change the selection mode, add a navigation indicator to single rows, or add a highlight to specific rows, you need to create a table with the corresponding settings. You do not need to define anything else. Hand this table over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on). This method allows you to use the multi-selection plug-in with the grid table, tree table, and analytical table.

    Column Visibility

    • Columns are created automatically. Items are rendered based on the properties and metadata of the underlying OData service (annotation: LineItem, properties: entitySet, tableBindingPath, initiallyVisibleFields, ignoreFields). A column is generated for each OData entity property.
    Developer Hint
    If a column needs to be in the model but should not be shown, you can hide it from both the table and the P13n dialog (property: ignoredFields, annotation: UI.Hidden).

    Use this option if:

    • A column is needed to provide an ID that is used for navigation purposes only. However, you only want to display the corresponding text on the UI, and not the ID.
    • The values of a column are needed to perform calculations, but only the results are shown on the UI.

    You can use the property requestAtLeastFields to request additional (technical) columns with every request, regardless of whether these columns are currently visible. This does not work with the analytical table.

    The property ignoreFromPersonalization is only available with the analytical table. It loads additional key fields that are needed for aggregations but are never visible.

    Developer Hint
    Columns can be removed at runtime. This is useful if the same table is used for similar, but slightly different objects. For one of the objects, specific columns need to be shown, for others they must be hidden, and users must not be able to add them in the personalization settings (function: deactivateColumn).
    • You can define which columns are initially visible when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleFields).
    Guidelines

    • Keep the number of initially visible columns to a minimum. Avoid pop-in behavior (responsive table) or horizontal scrolling (all other tables) on a tablet screen size in the default delivery (annotation: PresentationVariant/ LineItem).
    • Also keep the number of additional columns offered in the personalization settings to a minimum. You can use the P13n dialog to let users 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 each column that is initially visible, the LineItem annotation includes a DataField record, which allows you to influence the content rendering of the smart table.
      For columns that are initially invisible, the content rendering can also be influenced via the annotation DataFieldDefault.
    Developer Hint
    If the same column is defined via LineItem and via DataFieldDefault, LineItem wins.

    Column Layout

    • A default column width can be calculated for each column based on the data type, the column label, the edit/read-only state, and the annotations: textArrangement, MaxLength for strings, Precision and Scale for numeric data (property: enableAutoColumnWidth).
      The calculated width is between 3 rem and 20 rem. Apps can change this default width if needed (annotation: CSSDefaults).
      If the combined width of all the columns is less than the width of the table, the remaining space stays empty.
    Guidelines
    Choose a column width that avoids truncation for the initial data and (if feasible) for the column header label. If the default column width doesn’t fit, change it.
    Developer Hint
    For the responsive table, enableAutoColumnWidth also applies the following changes:

    • The smart table property demandPopin is set to true.
    • The responsive table property fixedLayout is set to Strict.
    • The responsive table property contextualWidth is set to Auto.
    • Column resizing is enabled for all columns (including custom columns).
    • Labels in the column headers no longer wrap. If there is not enough space, they truncate.

    In this case, the properties above must not be managed by the app.

    Responsive table with automatically calculated column widths, resizing, and remaining space
    Responsive table with automatically calculated column widths, resizing, and remaining space
    • If the automatically generated content does not fit for your use case, you can override the automatic behavior with your own column template.
      You can also add further columns. This allows you to provide columns with app-specific or inline actions, columns which show calculated values (based on more than one OData entity property), or – for responsive tables – columns that show more than one control.
    Developer Hint
    To add or override columns (“custom columns”):

    • Use an XML view to define the underlying table with just the columns to be added/overridden.
    • To override columns, provide the column key of the column you want to exchange.
    • Add this “unfinished” table to the smart table. The smart table adds all the automatically generated columns and additional features.

    Make sure that the sortProperty and the filterProperty are set (define p13nData via the aggregation CustomData). If you offer the export to spreadsheet option,  ensure that it works as expected.

    If you are using a responsive table, also make sure that the responsive behavior for this column works as expected (sap.m.Column, property: importance).

    Column Headers

    • You can specify a column header text for each column (annotation: sap:label).
    Guidelines
    Provide a column header text for each column. (annotation: sap:label).
    • The column headers contain the following settings:
      • Sort
      • Filter: Opens the P13n Dialog. If this does not fit for your use case, exchange this menu item (property: enableCustomFilter)
      • Group (only analytical table, only on dimension columns)
      • Total (only analytical table, only on measure columns): This setting is not persisted (annotation: sap:aggregation-role, value: measure).
        If a column contains entries with different units of measurement, a Show Details link appears instead of the total. Clicking the link opens a popover showing the subtotals per unit of measurement.
      • Freeze (only available for grid table, tree table, and analytical table): Must be added manually.
    Guidelines
    Offer column totals by default for all columns where totals make sense (annotation: PresentationVariant).
    Developer Hint
    To add a Freeze option manually, declare the corresponding table inside the smart table in the XML view, and use the corresponding settings for this inner table.

    Clicking the column header reveals sort and filter options (responsive table)

    • Smart Table - Column Header - 1.82
    • Smart Table - Column Header Pop-over - 1.82
    Column header menu for a dimension column of an analytical table within a smart table
    Column header menu for a dimension column of an analytical table within a smart table
    Column header menu for a measure column of an analytical table within a smart table
    Column header menu for a measure column of an analytical table within a smart table

    Content

    The smart table offers the following options for creating columns automatically:

    1. You can render the smart table in either read-only or edit mode (with no option to switch), or allow users to switch between the two modes (properties: editable, useSmartToggle).
    2. In read-only or edit mode, the smart table renders the controls as listed in the table below, or uses the smart field for both modes. If you use smart fields together with the option to switch between read-only and edit mode, the smart table renders the read-only controls as in the list below, but uses the smart field for edit mode. The smart field limits the rendering options (aggregation: customData, key: useSmartField), but also allows for:
      • Better control of the visibility of a field per row (smart field, annotation: FieldControl)
      • Use of value help for input fields
    Developer Hint
    From a performance perspective, using the smart field is more expensive than using the controls provided by the smart table directly. With this in mind, follow the rules below:

    • For read-only tables, use the controls provided by the smart table.
    • For simple editing cases with no need for FieldControl or value help on input fields, use the controls provided by the smart table.
    • For more complex editing cases, use smart fields.
    • For switching between read-only and edit modes:
      • In read-only mode, use the controls provided by the smart table.
      • In edit mode, use either smart fields or the controls provided by the smart table, based on the guidance above.

    In cases where the controls are rendered by the smart table, the following controls are used:

    Read-only Edit Annotations / Edm type Comment
    Static text Text Input field Edm.String
    Decimal numbers Text Input field Precision, Scale, Edm.Byte, Edm.Decimal, Edm.Double, Edm.Int16, Edm.Int32, Edm.Int64, Edm.SByte, Edm.Single
    Status information Object status or Icon Input field Criticality, CriticalityType,
    CriticalityRepresentationType    		 Do not use editable status information.
    Key identifier Object identifier (responsive table)
    Text
    (all other tables)    		 Input field for the ID SemanticKey,
    Common.EditableFieldFor
    Text and ID Text, object status, or object identifier Input field for the ID TextArrangement Use together with the annotation mentioned above for static text, status information, or key identifier.

    Sorting, filtering, and grouping only works for the ID, even if the ID is not displayed.
    Links with/without quick view Smart link Smart link SemanticObject Smart links can be customized using the aggregation: semanticObjectController
    Dates Text Date picker Edm.DateTime, sap:display-format, value: date, IsCalendarDate
    Dates and times Text Date/time picker Edm.DateTime, Edm.DateTimeOffset
    Times Text Time picker Edm.Time
    Fiscal periods Text Input field IsFiscalYear, IsFiscalPeriod, IsFiscalYearPeriod, IsFiscalQuarter, IsFiscalYearQuarter, IsFiscalWeek, IsFiscalYearWeek, IsDayOfFiscalYear
    Amounts with currencies Two text controls Input field for the amount sap:semantics, value: currency-code In edit mode, the currency is shown as static text next to the input field.
    Phone numbers Link Input field IsPhoneNumber Opens the system application for making phone calls.
    Email Link Input field IsEmailAddress Opens the system application for writing emails.
    Pictures Image Input field IsImageURL Only available for the responsive table. In edit mode, the input field contains the URL to the image.
    Boolean Text Checkbox Edm.Boolean For read-only, the displayed text is Yes or No.

    In all cases, the smart table automatically takes care of the content alignment and formatting (except for custom columns).

    Input fields can be accompanied by a value help dialog (annotation: ValueList). If annotated, triggering the value help button opens a value help dialog. Within this dialog, you can provide a search field (annotation: ValueList, property: SearchSupported).

    If no ValueList annotation is provided, you can restrict the number of characters for an input field (annotation: MaxLength).

    You can provide additional controls, such as micro charts, rating indicators, progress indicators, and buttons, as custom columns (using an XML view). For custom columns, you must provide any read-only and editable content manually.

    Guidelines
    For inline actions, use a text-only or an icon-only button. Make sure the icon communicates the function clearly enough. Otherwise, use a text-only button.

    If the smart table is used with the responsive table, you can show the status of an item by displaying a highlight indicator on the left of the item (property: highlight).

    Behavior and Interaction

    The behavior is generally inherited from the underlying table, toolbar, variant management, export to spreadsheet, 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.

    Empty Tables

    If there is no data to show, the smart table renders a default text. This text can be overwritten by the app development team. The default texts are:

    • If a table is initially empty:
      No items available.
      Overwrite this whenever a hint can be provided on how to fill the table with data.
      (property: initialNoDataText, value: $NO_FILTERBAR)
    • 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.
      (property: initialNoDataText, value: $FILTERBAR)
    • 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.
      (aggregation: noData, changeable at runtime)
    • If the user has hidden all of the columns in the personalization settings, the following text is shown:
      Right now, there are no visible columns in the table. Please select the columns you need in the table settings.
      This text cannot be changed.
    Guidelines

    • For all other cases, provide instructions on how to fill the table with data (aggregation: noData).
    • The “no data” text can be exchanged at runtime. Use specific texts for different situations.
    • Avoid displaying a table without any items, especially when the app is initially loaded.

    An empty smart table
    An empty smart table

    Responsiveness

    The smart table acts exactly like the embedded controls. For details see:

    • Toolbar Overview
    • Infobar
    • Responsive Table via auto pop-in mode
      (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true).
      You can use the UI.Importance annotation to influence the priority of each column.
      You can provide a Show Details button to let users show/hide columns with low importance (property: showDetailsButton).
    • Grid Table, Tree Table, Analytical Table:
      These controls are not intended for use on smartphones. If you use a smart table with this configuration, ensure that you implement a fallback solution for small screens.
    Guidelines
    If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true). Ensure that the most important columns stay in the tabular layout as long as possible (annotation: UI.Importance). 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.

    Developer Hint

    • To change the layout of the pop-in area (Block, GridSmall, GridLarge), you need to create a responsive table with the corresponding settings (property: popinLayout). You do not need to define anything else. Hand this responsive table over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on).
    • Do not use the annotation UI.Importance together with the grid table, tree table, or analytical table. It hides columns with low priority on phones or narrow-width screens, without the possibility to show them again.

    Examples

    Responsive table within a smart table
    Responsive table within a smart table
    Grid table within a smart table
    Grid table within a smart table

    Top Tips

    • If you are using the responsive table, enable and configure the auto pop-in mode and use the Show Details / Hide Details button.
    • For custom columns, follow the guidelines of the respective table. If needed, use responsive paddings for aligning the content.
    • Enable only the features that are needed for your use case. Very small tables do not need to be sorted, filtered, grouped, and rarely exported. Don’t just add unnecessary features for consistency purposes.
    • If the page has a filter bar, don’t offer filtering for the table.
    • If you are using custom columns, make sure that any export and personalization features you are using also work for these columns.

    Properties

    The following properties are available for sap.ui.comp.smarttable.SmartTable:

    • The property: toolbarStyleClass is deprecated. Do not use it.
    • The property: useOnlyOneSolidToolbar is deprecated. Do not use it.

    Related Links

    Elements and Controls

    Implementation

    Select Dialog

    The select dialog enables users to select one or more items from a comprehensive list. The select dialog comes with a list of entries and a search field to filter the list.

    A more enhanced dialog for single selection and multiselection is the value help dialog as it offers range selection and excluding functions.

    Usage

    Use the select dialog if:

    • Users need to select one or more entries from a comprehensive list that contains multiple attributes or values.

    Do not use the select dialog if:

    • Users need to pick one item from a predefined set of options that contains one attribute or value only such as languages. In this case, consider using the combo box or select instead.
    • Your use case requires more enhanced functionalities such as a selection based on ranges. For the selection of values, consider using the value help dialog instead.
    • Your use case requires tabs, filters, or an Add New functionality in the select dialog. In this case, use a standard dialog instead.
    Information
    For more information on which selection control to choose, see the selection control overview.

    Responsiveness

    The display of the select control depends on the device. On phones, the selection list takes up the whole screen. On desktop and tablet devices it appears as a popover.

    Size S

    Single select dialog in full screen on smartphone
    Single select dialog in full screen on smartphone
    Multi-select dialog in full screen on smartphone
    Multi-select dialog in full screen on smartphone

    Size M

    Single select dialog on tablet
    Single select dialog on tablet
    Multi-select dialog on tablet
    Multi-select dialog on tablet

    Size L

    Single select dialog on desktop
    Single select dialog on desktop
    Multi-select dialog on desktop
    Multi-select dialog on desktop

    Components

    Dialog Header

    You need to set the title of the dialog header (1). We recommend the following form:

    Single selection

    Select

    Example: Select Product

    Multi-selection

    Select

    Example: Select Products

    Search

    The first element in the dialog is a standard search field (2).

    Info Toolbar

    The info toolbar (3) is only available in multi-selection mode. It shows the number of selected items in the following form:

    Selected :

    Example: Selected Products: 2

    Content

    The content area (4) can be filled with any list content inherited from the list item base, such as standard list items, display list items, and feed list items. You can set the content to be displayed as grouped.

    Button Toolbar

    The button toolbar (5) contains two buttons: Select and Cancel. Select takes over the selection, while Cancel resets the selection to the state it was in when the dialog was opened.

    Components of the select dialog. Left: single select, right: multi-select
    Components of the select dialog. Left: single select, right: multi-select

    Behavior and Interaction

    The select dialog can be called up from any control. The most common trigger is an input field with selection icon, also known as a “value help field”, or F4. Alternative triggers are buttons or icons, which add items to an existing list or the infobar in the master list in order to apply a contextual filter.

    Single Select

    Once users select an entry, the select dialog is closed and the selected entry is taken over. If applicable, the entry is displayed in the field from which the dialog was triggered.

    Multi-Select

    In the multi-select version of the select dialog, checkboxes are provided for choosing multiple entries. The selection is taken over when the user closes the dialog via OK. Cancel closes the dialog without taking over the selected values. An infobar indicates the number of selected items.

    Search

    The user can search items.

    Resize and Drag Dialog

    You can make the select dialog resizable and draggable by setting the corresponding properties (also called resizable and draggable) to “true”.

    A resizable dialog makes sense if the items inside have long names or descriptions.

    A draggable dialog allows users to see the app content behind the dialog.

    Guidelines
    Both features are optional. However, even if you only need one, always set both of them to “true” to ensure consistency.

    Guidelines

    List Options

    If you need to indicate that none of the selection options are selected, or you need to allow the user not to select an option, provide (None) as an option and place it at the beginning of the list.

    If you need to indicate that all items apply (for example, as a list filter), provide All as an option and place it at the beginning of the list.

    Select list with '(None)'
    Select list with '(None)'

    Search Behavior

    Two types of search behavior are available:

    (1) A live search, also known as “search-as-you-type” (property: liveChange), which is triggered by each character that the user enters or deletes.

    (2) A manual search, which is triggered explicitly after the user enters text in the search field and clicks the Search icon or presses the ENTER key.

    Although app developers need to decide themselves which search to use, we recommend implementing the live search whenever possible. Use the manual search only if the amount of data is too large and your app would otherwise run into performance issues. For more information, check out the article on search.

    Reset/Remember Selections

    By default, the selection is reset when the dialog is closed. This allows users to make a new selection when they reopen the dialog and makes sense when users need to add multiple items to a table.

    Selection is reset after the dialog is closed
    Selection is reset after the dialog is closed

    However, if your use case requires selections in a dialog to be remembered so that the user can make corrections, you can set the rememberSelections function in the select dialog to “true”. When users exit the dialog by clicking Cancel, the selection is then restored to the state it was in when the dialog was opened.

    Selection is remembered after the dialog is reopened
    Selection is remembered after the dialog is reopened

    This also works in single-select dialogs. There, if users click the remembered item again, the dialog closes and they do not have to explicitly click Cancel.

    Infobar

    In multi-selection mode, an infobar shows the number of selected items. Use the following format:

    Selected: [Number of selected items]
    Example: Selected: 2

    Note that the infobar is not “sticky”. When the user scrolls down the list, the infobar scrolls off the screen.

    Infobar States

    The infobar has two states – active and non-active (non-clickable). For more information see Infobar States.

    Infobar - Active state
    Infobar - Active state
    Infobar - Non-active state
    Infobar - Non-active state

    “Clear” Button

    The Clear button allows users to clear all the selected items. By default, the button is not shown. To display the button, set the showClearButton property to “true”.

    Select dialog with 'Clear' button
    Select dialog with 'Clear' button

    Content

    By default, the select dialog comes with a growing feature (property: growing = “true”). We recommend disabling the growing feature and setting this property to “false”. This ensures that all items in the table are loaded at once, and that the “Items selected” count, the search, and select/deselect features all work properly.

    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

    Link

    A link (also known as hyperlink) is an interactive text element.

    Different links visualizing the various link types
    Different links visualizing the various link types

    Usage

    Use a link if:

    • You want to navigate to another page.
    • You want to trigger an event.
    • You want to point to an object or person. If so, you can either navigate to the object’s/person’s details or display them in a quick view after the link is triggered.

    Do not use a link if:

    • You could use a button to trigger the action instead.
    • The link text is the key identifier of an object. In this case, use an actionable object identifier instead.
    • There is no target or reference to be linked to.

    Responsiveness

    The link can either truncate or wrap. Favor wrapping over truncating and keep the link text as short and meaningful as possible.

    For more information and guidelines on the responsive behavior of text, see Wrapping and Truncating Text.

    Wrapped (first) and truncated (second) link
    Wrapped (first) and truncated (second) link

    Types

    There are four different link types:

    • Default
    • Emphasized
    • Subtle
    • Link with icon
    Guidelines
    Use a meaningful link text that indicates what will happen when the user interacts with the link (for example, Open Sales Order). Avoid texts such as Click Here or Link, as these do not meet accessibility standards.
    Default, emphasized, subtle link, and link with icon
    Default, emphasized, subtle link, and link with icon

    Default

    Use a default link if you want to display a simple link.

    Default links
    Default links

    Emphasized

    Use an emphasized link for extraordinarily important links that need to attract the user’s attention quickly.

    Emphasized links
    Emphasized links

    Subtle

    Use subtle links to distinguish between important (default) and less important (subtle) links when the app page is full of various links (10+). Subtle links allow you to improve the visual hierarchy in large data lists and tables.

    Subtle links
    Subtle links

    Link with Icon

    Use the link with an icon when the user expects and profits from the icon in the UI context. Please note that the icon is supportive, which means that it supports the text next to it. Therefore, a tooltip is not required. Do not use the icon for additional information.

    Guidelines
    Use the link with icon only if the icon is internationally well-known and easily understood. For example,  (world),   (calendar), or (theater).
    Links with icon
    Links with icon

    Behavior and Interaction

    To trigger the event or navigation, the user clicks the link. It provides visual feedback for “hover” and “focused” states.

    If the link cannot be triggered due to, for example, a disabled content area part, display the disabled state.

    Default, hover, focused, and disabled link
    Default, hover, focused, and disabled link

    Resources

    Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

    Elements and Controls

    Implementation

    Object List Item

    The object list item offers a quick overview of an object within a list. Typically, it is used in the list of a list-detail application using the flexible column layout. The object list items usually allow the user to navigate to the details of an object. Therefore, the object list item should only contain essential information that is necessary for the user to identify which object to work on first.

    Object list item
    Object list item

    Responsiveness

    The object list item’s text sizes are limited due to truncation. The title wraps once and truncates after two lines. The key attribute also truncates if it does not have enough space. Apps therefore need to use formatters, for example, to transform 1,659,963,900.42 into 1.7 B. (Note that this transformation is language-specific.)

    Status texts (on the right) and object attributes (on the left) do not wrap, but only truncate. Status texts can have a semantic color (to reflect the state) and an optional icon. The object attributes are placed next to the status texts. If they do not have a neighboring status text, they use the full width available for the list item.

    Components

    The object list item provides the following optional data:

    • Title of the object instance, which acts as the main identifier (title)
    • Key attribute (number) + unit (numberUnit)
    • Object status (sap.m.ObjectStatus)
    • List of object attributes (sap.m.ObjectAttribute)
    • Introductory text indicating the origin of the object, such as Forwarded by… or On Behalf of… (intro)
    • Icon that identifies the object (icon)

    The first status line can contain indicator icons for locked items, favorites, or items that have been flagged for follow-up.

    Object list item examples (with attributes, status, locking, flag, and favorites)
    Object list item examples (with attributes, status, locking, flag, and favorites)

    Behavior and Interaction

    List item behavior and interaction is similar for all list item variants and is therefore described in the list overview article.

    Guidelines

    • An icon in front of the title requires a lot of space. Ensure there is sufficient space available if you are planning to use one.
    • This control can only throw one event. Therefore, object list items cannot contain an additional link.
    • Display the date  within the title in the long format and within the attributes in the medium format.
    • Avoid long descriptive texts. They may not be displayed due to truncation.

    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

    Feed and Notes

    Information
    The picture of a person is supposed to be displayed in a circle as described in the avatar article. The images of this article will be updated shortly.

    Feeds and notes are commonplace in many SAP Fiori applications. The sap.m.FeedInput control allows users to input and post plain text, while the sap.m.FeedListItem control handles and displays this text. Both can be used individually, but they also complement each other well to create a simple feed or notes control.

    Usage

    Feed Input

    Use the feed input if:

    • A user needs to input small amounts of text without formatting.
    • You expect multiple instances, such as notes or feed entries.

    Do not use the feed input if:

    • The user needs to format the text (rich text editor).
    • You need only a single text box instance. In this case, use the text area (for multiple lines) or the text control (for a single line).

    Combination of Both Controls (as Feed or Notes Control)

    Use both controls if:

    • You need a feed to show textual posts.
    • Your users need to input notes.

    Do not use both controls if:

    • You expect extensive social interaction in the feed.
    • Users need to reply at item level instead of creating a new post.
    • You want to display SAP Jam feeds.

    In these cases, use the social timeline instead (requires SAP Jam).

    Responsiveness

    Due to their responsive behavior, both controls can be used in small and large view ports or screens.

    For better usability, we highly recommend that you do not stretch the controls across the full width on large screens – 2/3 or even 1/2 works just fine. This can easily be achieved using the grid layout .

    Feed – Size S
    Feed – Size S
    Feed – Size M
    Feed – Size M
    Feed – Size L
    Feed – Size L

    When the width of the available space falls below 25 rem (for example, in portrait mode on smartphones), the two controls respond as follows:

    • If a user image previously appeared in the feed input, it will be omitted in narrow screens to give the text field more space.
    • If there is no user image, there will be no visual change.
    Feed input – Responsiveness
    Feed input – Responsiveness

    In the feed list item, the user’s name, image, and the time stamp move on top of the text. If there is no image, the name and time stamp are left-aligned together with the text.

    Feed list item – Responsiveness – With image
    Feed list item – Responsiveness – With image
    Feed list item – Responsiveness – Without image
    Feed list item – Responsiveness – Without image

    Layout

    Feed Input

    The feed input consists of:

    • A text input field with a placeholder (input prompt)
      Example: Add a comment
    • A Send button
    • An optional user image

    You can also choose not to show user images at all. In this case, the size of the input area increases automatically.

    Feed input – Layout – With user image
    Feed input – Layout – With user image
    Feed input – Layout – With generic user image
    Feed input – Layout – With generic user image
    Feed input – Layout – Without user image
    Feed input – Layout – Without user image

    Feed List Item

    The feed list item consists of the user’s name and an optional picture of the user who wrote the note or update. The name can contain a link that triggers a quick overview of the user’s profile data. The actual text written by the user follows the name. Below it is a separate byline that can contain a time stamp and an attribute in the form of free text. This allows you to put in your own attribute, such as Approval, Internal, or External. Both the time stamp and the attribute are optional.

    If the name is a link, the picture should also be linked with the same attributes.

    Feed list item – With user image and linked name
    Feed list item – With user image and linked name

    If the user does not have a picture assigned, a placeholder is shown instead:

    Feed list item – With generic user image and linked name
    Feed list item – With generic user image and linked name

    The name (and picture) can also be read-only, that is, without a link:

    Feed list item – With user image but without links
    Feed list item – With user image but without links

    If the app does not support user images, they can be omitted:

    Feed list item – Without user image but with linked name
    Feed list item – Without user image but with linked name

    Here, too, the name can be read-only:

    Feed list item – Without user image and read-only name
    Feed list item – Without user image and read-only name

    It’s also possible to display rich text (formatted text) in the feed list item. This feature should be handled with care as it allows for countless custom layouts.

    Please see that you use it responsibly and provide your users with a consistent experience. Only deviate from the default layout and font if absolutely required by the use case.

    Example use case: Render URLs as links.

    Feed list item – Layout – Rich text
    Feed list item – Layout – Rich text
    Information
    The items in the feed list must be homogeneous. This means that they must contain the same layout and visualization. For example, it is not possible to have a feed containing both linked and plain names, or both user images and default images.

    Special Case: Multiple Types of Notes

    Apps sometimes need to discern between different types of notes. There is an easy way to allow users to choose which type they want to see or add to the list.

    You can place a toolbar containing a select control at the top of the feed input control. From there, users can select the type of notes, such as Internal Notes or External Notes. The list of notes must contain only the type selected. If the user adds a note via the feed input, the type must be set automatically according to the selection.

    Interaction – Note Types

    Components

    The feed input and feed list item do not contain subcontrols. However, you can easily combine them to create a simple feed or notes control.

    Although the feed input counts as a single control, the input area inherits its behavior from the sap.m.TextArea control.

    Behavior and Interaction

    Send Message

    Initially, the feeder contains a placeholder (input prompt), and the Send button is disabled, with reduced opacity.

    Clicking into the input field puts the focus on the field and allows to start typing.

    When the user starts to type, the placeholder disappears and the Send button becomes active and more prominent.

    If the available width is below 25 rem (for example, in portrait mode on a smartphone), the picture is removed.

    To send the text, the user must explicitly click the Send button. Pressing Enter on the keyboard (on-screen or physical) results in a line break.

    Feed input – Behavior
    Feed input – Behavior

    Show More Text

    When the text exceeds a certain number of characters (you can overwrite the default value), the rest of the text is truncated and a MORE link appears after the truncated section.

    The MORE link indicates the possibility of expanding the section of the feed list item itself. Hovering over the link underlines it.

    Show Less Text

    When the user expands the text, the name of this link changes to LESS,  but still behaves the same way as before.

    Both texts for the “MORE” / “LESS” links can be modified to suit a particular use case.  There is a possibility to use uppercase, lowercase or a mix of them.

    MORE link (1)
    MORE link (1)
    MORE link (2)
    MORE link (2)

    Feed and Notes in Tables

    In tables, users sometimes need to see if an object has a comment (or feed or note) without further navigation, and even be able to add/edit right from the table.

    Add an additional column, named according to the type of user input, such as Comment, Note, or Feed.

    Place a link inside each cell with the appropriate action (row: Comment, link: Comment/ row: Feed, link: Post).
    If there can be more than one item, add a counter after the text as well (see example on the right).

    This solution works with every table control.

    Feed and notes in tables (1)
    Feed and notes in tables (1)

    Optional:
    Depending on the use case, it might help users if they can see the latest note. The responsive table allows the feed list item (sap.m.FeedListItem) to be used inside a cell.

    Reduce the property “maxCharacters” to an amount that your table can handle.
    Note that once the maximum number of characters has been reached, a MORE link allows users to expand the text. Technically, this is no problem for the responsive table, but you need to ensure that the layout of your page allows this kind of expansion.

    Place a link below the feed list item to allow users to add something (as described above).

    Feed and notes in tables (2)
    Feed and notes in tables (2)

    When the user clicks a link, such as Comment or Note, display a dialog showing all comments (notes, feed entries, and so on) along with possible actions, such as Add or Edit, depending on your use case.

    There are several ways to show notes (comments, feed entries, and so on) in a dialog:

    • You can use the feed list item (and feed input) as described in this article.
    • If only one single note is allowed, you can use the text area.
    • For a large feed, you can use the timeline control (SAP Jam is required for social features).

    Actions On Feed List Items

    Applications can define actions that users can perform on individual feed posts. The two most typical actions are Edit and Delete. Other actions can be introduced as required by the use case. To keep the feed as lightweight as possible, don’t overwhelm users with too many actions or complicated actions (max. 5 per post).

    Interaction - Actions
    Interaction - Actions

    Styles

    By default, feed entries are separated by divider lines. We recommend that these separators remain enabled, since they help distinguish between individual posts. However, if your list is expected to hold only a handful of entries, you can disable the separators by setting the showSeparators property at list level (not at list item level) to none.

    Guidelines

    Because the feed list item is built on the basis of the standard list item, it inherits multiple properties that may not make sense in a feed use case.

    Use only properties that are described in this article. Especially making the entire feed list item clickable can lead to functional issues and usability problems.

    Don’t stretch the feed input or the feed list items across large screens (size L and beyond). This will have a negative effect on usability and readability. Instead, only use 1/3 or even 1/2 of the screen. Implement this with the grid layout .

    If you display formatted text (rich text) in the feed list item, use formatting that is beneficial to users, not decorative formatting. Use formatting responsibly, and provide your users with a consistent experience. Deviate from the default layout and font only if absolutely required by the use case (example: render URLs as links).

    Resources

    Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

    Elements and Controls

    • No links.

    Implementation

    Message Popover

    The message popover control can display multiple messages of different types in one list. For example, it might show several messages related to entries in a form, or messages triggered by a finalizing action, such as Save.

    The message popover is used in conjunction with a technical message manager, which populates the message list. If an error occurs at a validation point, the corresponding message is added to message popover automatically, without interrupting the user.

    Users can browse messages by type and navigate to the message details. In some cases, they can also jump directly from the message to the affected field on the UI.

    Message popover
    Message popover

    When to Use

    Use the message popover if:

    • You want to display multiple messages to the user.
    • You do not want to interrupt users while they are performing an action.

    Do not use the message popover if:

    • You need to interrupt the user. In this case, use a message box.
      (Typically, interrupting the user is only necessary for technical problems, such as network errors and connection issues.)

    Components

    (1) Filter bar
    (2) Message short text
    (3) Message subtitle
    (4) Section/subsection on the UI
    (5) Message button
    (6) Navigation to message details
    (7) Counter for aggregated messages

    Components of the message popover
    Components of the message popover

    Filter Bar

    Initially, the filter bar shows all the different message types in the list (1).

    Segmented buttons at the top of the message popover allow the user to filter the messages by type (error, warning, success, and information).

    List

    Short Description

    The short message text (2) provides a simple and helpful short message. It’s the same message as the one attached to the UI control where the issue occurred.

    Subtitle

    You can use the subtitle (3) to give your message an identifier. If the message relates to a specific field, show the label of the field where the error occurred. Based on the subtitle, the user should be able to identify the corresponding UI control on the UI (for example, the input field in a form).

    Section/Subsection

    Messages in the list are grouped by the section and subsection on the UI (4). This helps the user to find the part of the UI that triggered the message.

    Navigation to Message Details

    If message details are provided, the message popover automatically provides a chevron on the right-hand side for navigating to the message details page (6).

    Aggregated Messages

    If your app team wants to aggregate messages, they can use the counter property of each list item (7). Note that the message popover only provides the counter property. The aggregation itself must be implemented by the app team.

    Message Button

    If there are messages to display, the message button indicates the most critical message status in the list (5).

    For example, if the list contains error messages, the message button inherits the error icon and semantic color. If the most critical message in the list is a warning, the message button shows the warning icon and corresponding semantic color, and so on.

    In addition, the error button contains a count indicating the number of errors.

    Message button types - Error with counter, warning, success, information
    Message button types - Error with counter, warning, success, information

    If there are no messages to display, there is no message button. In this case, the footer toolbar contains only the “normal” actions for the task.

    Message Details

    The message details page shows:

    • The message short text (1).
    • A more detailed message text to explain the issue and propose a solution (2).
    • An optional link to more information, such as app documentation (3).
    Detail page of the message popover
    Detail page of the message popover

    Behavior and Interaction

    When Does the Message Popover Open?

    Form Field Validation

    If one or more errors occur when the user fills out a form, the message button appears, indicating the message type of the most critical message. The message popover does not open automatically. For more information on the different validation points, see Form Field Validation.

    Form field validation behavior
    Form field validation behavior

    Finalizing Actions

    If the user activates a finalizing action (such as Create, Save, or Submit), the message popover opens automatically to inform the user about the errors on the UI that need to be resolved first.

    Message popover triggered by a finalizing 'Save' action
    Message popover triggered by a finalizing 'Save' action

    Navigation to the Second Page

    If the message provides a long text from the back-end system, the user can navigate to a second page within the message popover. There, the user will typically find more information and help.

    Navigation to the detail page of the message popover
    Navigation to the detail page of the message popover

    Navigation to the Relevant Field

    The navigation link takes users directly to the field on the UI that triggered the message. This can be a field in the visible area, a field somewhere else on the same page, or a field on another tab or screen.

    Guidelines
    Always add a navigation link, where possible.

    For more information about the navigation, see Navigating to the Corresponding Field on the UI in the Message Handling article.

    Developer Hint
    Set the navigation link with the activeTitlePress event. This allows users to click the message text in both the first and second page of the message popover.
    Navigation from the message text to a field on the UI
    Navigation from the message text to a field on the UI

    Responsiveness

    Size S (Smartphone)

    On smartphones, the message popover is automatically shown in full screen mode.

    Full screen message popover on a smartphone
    Full screen message popover on a smartphone

    Top Tips

    • Whenever possible, provide a navigation link from the message to the relevant field on the UI.
    • Use the message subtitle to indicate the field label.
    • In forms, also highlight the individual fields, and change their value state according to the type of message. For more information, see Form Field Validation.

    Related Topics

    Elements and Controls

    Implementation