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.

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.

Layout

Filter Bar (Page Title)

Table

If the table has a separate title, place the title first.

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

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.

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.

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.

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.

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

Components

Behavior and Interaction

Business Actions (app-specific)

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.

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.

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.

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:

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.

If the app does not need a perspective switch, use the chart title (property: title).

Legend (Generic)

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.

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.

View Switch (Generic)

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.

Maximize / Minimize

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

The footer toolbar always appears as floating footer at the bottom of the screen. The floating footer property creates some padding between screen and toolbar, improving visibility.

The control is used for closing or finalizing actions that impact the whole page. It is only visible when actions appear, when message handling is visible, or when the draft indicator is displayed. One main advantage of the footer bar is that this bar is always visible and will not scroll away.

Our general guideline is to use only icon buttons or text buttons. Icon and text should not be combined into one button. Buttons are always right-aligned.

Buttons are sorted from frequently-used to seldom-used. This ensures that the most important buttons will go into the overflow last.

Usage

Use the footer toolbar:

• If you have closing or finalizing actions on your page that apply to the whole page.

Do not use the footer toolbar:

• If you have different containers on your page (such as charts, tables, and forms) and the action influences only certain items. In this case, place the action as close to the corresponding item(s) as possible.
• If you have global actions (such as Edit or Delete) that are not finalizing or closing actions. In this case, use the header toolbar instead.

Responsiveness

To enable responsiveness, use the OverflowToolbar control. For more information, please refer to the corresponding section in the toolbar overview article.

The height of the toolbar changes on desktops (compact mode), tablets, and smartphones (cozy mode). For more information about cozy and compact modes, see content density.

Components

The footer toolbar can contain the following components:

• Message indicator
• Draft indicator
• Finalizing/closing actions

All closing or finalizing actions are placed on the right side of the toolbar.

The footer toolbar can also include a message and draft indicator. For more information, see draft handling and messaging.

Behavior and Interaction

Our general guideline is to use only icon buttons or text buttons. Icon and text should not be combined into one button. Buttons are always right-aligned.

The buttons are sorted from frequently-used to seldom-used. This ensures that the most important buttons go into the overflow last.

App-Specific Actions

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

Text vs. Icon Buttons

Use text-only buttons for all finalizing/closing actions (such as Save).

Styles

• Use button styles only if they help the user, and not for decoration.
• Use the emphasized button for primary actions, such as Save.
• Use the ghost button style for secondary actions, such as Return, and the transparent button for negative path actions, such as Cancel.
• Use the semantic button for positive/negative actions (property: type = accept or reject).
• Use only one emphasized button per toolbar and never mix emphasized and semantic buttons.
  Exception: Additional messaging button for the message popover.

For more information, see Button and Action Placement.

Guidelines

Resources

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

The responsive table 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.

Usage

Use the responsive table if:

• You need a table to display a moderate amount of data. When your data is of average complexity, the responsive table can handle up to 200 items. However, more complex data lowers the limit, and less complex data raises it. Note that the limit is not on the number of items in the database or in the filtered results, but the volume of data loaded at any point. Factors that influence the exact limit include:
  • The number of loaded 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 the page)
  • The browser used

  For loading large amounts of complex data, use a grid table instead, as it can handle higher volumes more efficiently.

• 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 a single implementation for all devices. As its name suggests, the table is responsive and adjusts its appearance to the screen size so you can use it on all devices. However, make sure you adapt the responsive table design to offer the best solution for the tasks performed on mobile devices. Sometimes, a solution without a table is more useful and usable.

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 users to work with large amounts of complex data. Use the analytical table or grid table instead; they are optimized for those cases.
  Note that the analytical table and the grid table are not fully responsive, but available only 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. In 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 the analytical table isn’t fully responsive and 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.
• 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.

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.

The responsive behavior is optional. If it is not used, the responsive table minimizes all visible columns until they are no longer readable. The priority level assigned to columns also impacts the display of the responsive table. For more information on the priority levels, see: Smart Table

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 area. 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 area 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 area (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.

Example for GridLarge Layout

Behavior and Interaction

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

Table Level

Column Header Level

The column header provides the label for the corresponding column. It also handles the functionality for resizing columns.

Line Item Level

Edit Line Items

Click an Item

Drag and Drop

Context Menu

Cell Level

Showing Information

Add Controls

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

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 (“:”).

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.

Selection

Loading Data

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 empty space.

Optimize the column width for its initial content (sap.m.Column, property: width). If the content is dynamic, optimize the column width for typical content.

When defining the column width, consider the implications when a column is resized:

• If you define the column width in pixels or rem, resizing a column only affects the width of that particular column.
  • If the table isn’t wide enough to show all the columns after a column has been resized, one or more of follow-on columns move into the pop-in area.
  • If the columns don’t use up the available space, white space appears to the right of the last column (property: fixedLayout, value: strict).
  • If only one column remains, and the width of this column exceeds the width of the table itself, the width of the column is reduced to the width of the table.
• If you define the column width as a percentage, resizing one column affects the width of several or all columns. Text wraps more when the browser window size is reduced. This ensures that all columns together make use of the full table width.
• If you define the column width as “auto”, the behavior is the same as for “percentage”. However, unlike “percentage”, “auto” distributes the columns equally.
• Be cautious of 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 columns are resized. If you are using percentage-based widths for one or more columns, consider not allowing end users to resize columns at all.

If you need more columns than those that fit on a tablet screen (usually five) to fulfill 80% of your main use cases, offer an option to add, remove, and rearrange columns via the table personalization dialog. Before doing so, try to reduce the number of columns, for example, by using several lines per column or by utilizing the pop-in function. See the cheat sheet for an example.

Column Headers – Best Practices

Within the column header, provide a label for each column (sap.m.Column, aggregation: header). The column header label is reused as a label in the pop-in area.

Exception: If the column does not pop in, no column header label is needed as long as at least one column still has a column header label.

To keep the column headers readable, wrap or truncate the texts as follows:

• If columns are not resizable, use controls that wrap and support wrapping with hyphenation, such as text (with wrapping and hyphenation enabled). Do not use controls that truncate.
• If columns are resizable, use controls that truncate.

Keep column headers sticky.

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.

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

Right-Align

Center-Align

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.

Content Formatting

The responsive table provides flexibility, including multi-line cells, by enabling every control to be put into a cell.

Avoid truncation. Use controls that wrap the text and support hyphenation.

For example, use text.

Item States

Show only one state at any one time.

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.

Currently, there is no keyboard support for 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).

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.

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.

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

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

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.

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: Add, Remove, Rearrange Columns

To enable users 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.

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

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.

Paste

The browser paste function can be used to paste data from the clipboard to the table if the focus is on an editable control within the table. The browser paste is triggered with the Ctrl + V keyboard shortcut, the table toolbar action, or actions in either the browser context menu or the table generic context menu.

The pasting of a new row or cell follows the responsive table inline creation paradigm, where new items are created at the bottom of the table. The same happens when the data is pasted and a row is unselected or focused.

Note

Pasting via the browser context menu is unavailable if the table has its own context menu because table context menu takes precedence over the browser context menu.

Paste (Overwrite)

Pasting overwrites data present in the table only when a cell with data is selected prior to pasting. When a single cell is selected, all the data in the clipboard is pasted into the table, extending from that cell. The paste will overwrite the data contained in those additional cells, too.

Clipboard Selection behaviour

If the clipboard has larger data set than the range selected for the paste, only the cells contained within the selection are updated.

On the other hand, if the clipboard has a dataset too small to fill all the cells selected for the paste, the pasted data updates only the selected cells for which there is data.

Read-Only

The paste action does not update read-only cells, even if there is data in the clipboard corresponding to those cells. Instead, it updates only the surrounding write cells.

Example

If the clipboard contains a range of four columns, and that data is pasted into a table, where column 2 is read-only, only the cells in column 1, 3, and 4 are updated.

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.

The filter bar lets users set criteria to limit the data loaded and displayed in a table. It is part of the list report and the overview page, and is also available as an alternative layout to the visual filter bar in the analytical list page.

It is made up of input controls that filter objects according to various criteria, such as status or date. Users can adapt the filter bar, for example, by showing and hiding input controls or changing their order. They can also store the current set of filter criteria in a view.

The filter bar is displayed in the header area of a list report, overview page, or analytical list page. Because these floorplans are based on the dynamic page layout, the expand and collapse header functions are available.

When to Use

The filter bar is always part of the list report and overview page.

Do not use the filter bar:

• In a table in an object page section. Use the filter in the View Settings dialog instead.
• In a wizard.
• In a simple list. Use the search instead.

Filter Bar Components

Expanded Filter Bar

The expanded filter bar consists of:

1. Views (optional)
2. Basic search field (optional)
3. Filter input controls
4. Go button (only for manual update mode)
5. Adapt Filters button

Views (1) store the settings for the filter bar, including the values of filter input controls, the fields visible in the filter bar, and their order.

You can also use the filter bar without view management. In this case, display a page title instead.

If the basic search field (2) is available, it is displayed first. It allows users to filter the results with a given keyword. Unlike the other input control fields, the basic search field has a placeholder text instead of a label.

The filter input controls (3) are arranged in a horizontal, linear layout, with a label above them. An asterisk next to the filter label indicates the filter is mandatory.

If the browser window size is reduced or filter input controls exceed the available width, they wrap to the next line. The height of the expanded filter bar is not limited and adjusts to accommodate the visible filters. The size of the widest input control is inherited by all other filters to ensure visual cohesion.

The full labels for the filter input controls are always displayed. They are displayed without wrapping on all screen sizes but S. On an S-sized screen, they are displayed with wrapping.

The Go button (4) triggers the search for the manual update mode. Alternatively, you can offer the live update mode where the table results are updated each time the user changes an input control value. For more information, see Behavior and Interaction.

In most cases, only a subset of all available filters is visible in the filter bar. Users can control the visibility and order of the filters and assign values to them in the Adapt Filters dialog (5).

Next to Adapt Filters, the number of active filters is displayed in parentheses. A filter is active when a value is assigned to it either in the filter bar or the Adapt Filters dialog. Note that a filter can be active, but not visible in the filter bar.

Collapsed Filter Bar

The collapsed filter bar takes up very little space, leaving most of the screen to display the results.

It shows a summary of the filters currently applied:

• Either 1 filter active or <n> filters active, where “n” stands for the number of applied filters.
• A comma-separated list of the currently applied filters for up to five filters. If there are more, an ellipsis (…) shows at the end of the string.

If no filters have been applied, the summary text is No filters active.

“Adapt Filters” Dialog

Users can manage all the available filters in the Adapt Filters dialog, including their visibility and order in the filter bar and the values of filters both visible and not visible in the filter bar.

The Adapt Filters dialog consists of:

1. Select control and search
2. Show Values/Hide Values toggle
3. List or group view
4. Mandatory and optional filters
5. Footer bar buttons
6. Arrows to move the filter up and down
7. Active filter with assigned value

When opened, the dialog displays all the available filters in the Hide Values view with the List view.

The selected filters are visible in the filter bar and displayed in the same order as in the filter bar.

Searching and Displaying Filters in the Dialog

To find filters (1), users can search for them by name or use the select control to limit the filters displayed in the dialog to certain filter types, such as visible, active, or mandatory.

Mandatory filters have an asterisk next to their label (4). They must have values for the search to return results. Users can set the values either in the filter bar or the Adapt Filters dialog.

In the dialog, when a mandatory filter has:

• No value assigned, its checkbox is automatically selected and cannot be deselected.
• A value assigned, the users can deselect it to remove the filter from the filter bar.

In the dialog, users can display the filters:

• With or without the filter values (2).

When the values are hidden, a visual indicator (7) flags the active filters.

• In the list or group view (3).

The group view shows the filters according to group. The first group is called Basic and contains the filters for the standard view that you design to ship with the app. You can design additional views to ship with the app, but no additional groups are created for these views.

Displaying Filters in the Filter Bar

All the views in the dialog allow users to select filters to be visible in the filter bar.

In the Hide Values view with the List view, users can reorder the selected filters with the arrows (6).

In the Adapt Filters footer bar (5):

• OK applies changes and closes the dialog.
• Cancel closes the dialog without applying changes.

Resetting Filters

In the header area, Reset (8) (optional) restores the selected filters and filter values to the ones in the current view. Before the filters are reset, the user gets a warning because the reset applies immediately to the filter bar, even though the dialog stays open. Clicking Cancel in the footer bar does not reverse the reset action.

Filter Input Controls

To prevent unnecessary complexity in the filter bar, pick the simplest input control that works for your use case, as recommended below:

For a comprehensive overview of when to use which input field, see Which Selection Control Should I Use?

Use the value help control only as a last resort. It is especially beneficial if you want to offer an advanced function for selecting single or multiple items either inline (by entering text) or by means of a dialog.

For more information on the selection controls, see:

• Input
• Select
• Combo box
• Multi-combo box
• Multi-input
• Value help
• Date picker
• Date range selection
• Date/time picker
• Rating indicator

Behavior and Interaction

In the live update mode, the search results are updated each time the user changes the value of an input control or the search field. A Go button is not necessary.

As the user types in the search field, the search is triggered with the entry of each character. The table is updated with the results that match all the filter values and include the search term.

In the manual update mode, the search results are updated only when the users click Go or press Enter on their keyboard.

Responsiveness

The name of the view or title is always visible.

The filter area (basic search field, input controls, optional Go button, Adapt Filters dialog) varies:

• Desktop: Expanded or collapsed by default
• Tablet: Collapsed by default
• Phone: Not displayed. Accessible through filter dialog.

The labels for the filter input controls are displayed in full for all device sizes:

• On a desktop and tablet, without wrapping
• On a phone, with wrapping.

Examples

Top Tips

Filter Bar

Always provide a set of predefined default filters to deliver with the app (Basic group in the Apply Filters dialog). Include filters that are:

• Mandatory / crucial for the use case
• Frequently used
• Vital for reducing the number of items in the list

Users can set filters from the Basic group not to display in the filter bar, but cannot remove them from the Adapt Filters dialog.

Filter Input Controls

• Use the basic search field to provide a keyword search. Do not show a search field in the table toolbar.
• Pick the simplest selection control that works for your use case. See When to Use which Selection Control?
• For temporal filters, use the date picker or date range selector.
• To help the user enter a valid value for multi-input fields, enable suggestions.

Preset Filter Values

• Provide meaningful default values for as many filters as possible to prevent unnecessary data from loading. This is particularly important when the application has large data sets.
  Example:
  A default value for date ranges should reflect the time frame the user would normally apply.
• For list reports and overview pages, preset values for mandatory filters to prevent error messages when the page loads.

Update Mode

• Whenever possible, use the live update mode because it is more convenient for the user.
• Consider the manual update mode only in cases where:
  • The volume of unfiltered data to load would be excessively high.
  • The users need to enter multiple filter values to display results they can work with.

Related Links

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:

• Form – sap.ui.layout.form.Form (API)
• Simple form – sap.ui.layout.form.SimpleForm (API)

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.

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.

Breakpoints

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

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

Size L

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

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

• 4 grid columns of the responsive grid layout are used by the labels.
• 8 grid columns of the responsive grid layout are used by fields.
• 0 grid columns of the responsive grid layout are used by empty columns.

Size XL

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

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

• 4 grid columns of the responsive grid layout are used by labels.
• 8 grid columns of the responsive grid layout are used by fields.
• 0 grid columns of the responsive grid layout are used by empty columns.

Layout

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.

Size S (Smartphones and Dialogs)

Size M (Tablet) – Full Screen

Size L (Desktop Screens)

Size XL (Desktop Wide Screens)

Components

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

• Button and segmented button
• Checkbox
• File uploader
• Icon
• Image
• Input controls, such as the combo box, multi-combo box, date picker, date/time picker, dynamic date, time picker, input field, multi-input field, and mask input.
• Object number
• Object status
• Progress indicator
• Radio button and radio button group
• Rating indicator
• Search field
• Select
• Slider
• Step input
• Switch
• Text and text area

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

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.

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.