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.

A grid table contains a set of data that is structured in rows and columns. It allows users to scroll in both directions and is optimized for handling large numbers of rows 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 need a table to display large amounts of complex data. The grid table can handle higher volumes more efficiently than the responsive table.

The responsive table can handle around 200 items when data is of average complexity — more items when data is less complex and fewer when data is more complex. If your scenario exceeds these data limits, use the grid table. 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

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

• You’re going to implement inline creation and the sequence in which the items are created is important – the grid table creates new items at the bottom of the table.

• Your use case is for tasks performed on a desktop or tablet device. The grid table is not fully responsive.

Do not use the grid table if:

• You expect users to work with moderate amounts of data. Note that this is about the data actually loaded — not the items in the database or the filtered results — which includes the number of items as well as the complexity of the data displayed. In these cases, consider the responsive table.

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

• 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 not fully responsive, but available for only desktops and tablets, and it supports touch interactions. For mobile use cases, you need to:​

• Create a new Fiori application with reduced complexity, not an exact match of the desktop application.​
• With the new application, address the most important use cases for users in a mobile context. The responsive controls (responsive table, list or tree,) or a relevant control for your use case (for example a chart or the category navigation pattern) may suffice.

Or, 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.

Layout

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

Select

Selection Mode

Selection for a grid table depends on the chosen selection mode. The following options are available:

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

Column Header Menu

Sort

Filter

Freeze Columns

Line Item Level

Drag and Drop

Context Menu

Cell Level

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:

Selection

Single Selection

For single-selection list-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).

• In multiple selection mode (multi toggle), 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.

Loading Data

Errors and Warnings

Columns – Best Practices

Minimize the number of columns. Avoid the need to scroll horizontally in the default delivery.

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.

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.

Right-align numbers (except IDs).

This ensures comparability of numbers and amounts.

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.

Right-align dates and times.

This ensures comparability for most formats and locales.

Left-align status information.

Center-align icons.

Left-align micro charts.

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.

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, or if they need to 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 and filtering, either the string or the ID. This option is then used for all sort and filter actions and can’t be changed later by the user. Use this format only if users don’t need to sort and filter by both the string and the 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.

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.

Missing Value

If there is no value for a cell, leave it blank. Do not display text as N/A.

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.

Status

For status information, use semantic colors on the foreground elements.

For status information on text, use an object status.

Micro Charts

Use only the following micro charts: Bullet, comparison, stacked bar. When using micro charts, use them in size XS.

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 list-detail pattern instead of filter settings).

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.

Item States

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 row with errors should be highlighted in all use cases – for example when the field is visible in the row in edit mode.

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.

To show that an item is in draft state, add a transparent-style button with the text Draft in the Editing Status column.

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 and filtering by the unit of measurement are not needed.

For amounts, use a currency control to display the concatenated string.

Number and Unit in Separate Columns

The number and unit are in separate columns. Do this if sorting and filtering 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.

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

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.

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.

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 list-detail scenario
When a multi-selection table is used in a list-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.

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 and filter criteria to keep the item visible.
• Added: The item has been fully added. It follows the sort and filter 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 or filtering, 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).

Editable Content

View Settings

Sort

Filter

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.

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)

Tables in Object Pages

In the object page, you can use a responsive table or grid table and offer navigation to a list report with the table types mentioned above. In the object page, we advise using the analytical and tree tables  in tab mode.

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 grid 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 cell 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.

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, but does update 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.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.

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 interaction devices, but is not optimized for small screens. For smartphones, you need to take an adaptive approach by offering an additional UI.

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

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

Condensed Mode

Behavior and Interaction

Selection

The tree provides the following possibilities:

No selection: Items cannot be selected. (property: selectionMode = None)

Single selection: One item in the tree table can be selected. A row selector column is shown. (property: selectionMode = Single)

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.

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.

Column Header Menu

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

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:

• Text
• Label
• Object status
• Icon
• Button
• Input
• Date picker
• Select
• Combo box
• The following micro charts in size XS: Bullet, comparison, stacked bar
• Multi-combo box
• Multi-input field
• Checkbox
• Link
• Currency
• Rating Indicator
• Progress indicator

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.

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.

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

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.

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.

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 list-detail scenario
When a multi-selection table is used in a list-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

• 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 list-detail pattern instead of search and filter settings).

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.

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

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.

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, you can use a  responsive table or grid table and offer navigation to a list report with the previously mentioned table types. We advise you to use the analytical and tree tables in tab mode.

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.

Resources

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

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

Responsiveness

The analytical table is available for desktops and tablets, but not in smartphone sizes. It supports touch interaction devices, but is not optimized for small screens. If you use an analytical table, you need to take an adaptive approach by offering an additional UI for smartphones.

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.

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