How To Use Semantic Colors / Industry-Specific Colors

You can use semantic colors and industry-specific colors to visualize the status or state of business data:

Semantic colors denote standard value states (such as good, bad, or warning). Each color has the same basic meaning in all contexts.
Industry-specific colors reflect the color conventions in a line of business or industry. The meaning of each color depends on the business context.
In SAPUI5, industry-specific colors are called indication colors.

Nearly all input controls support semantic colors, while industry-specific colors are only supported by a few UI elements.

For information about the color values for other themes, see Belize Colors and Quartz Light Colors.

Object status with semantic colors

Object status with industry-specific colors

Usage

Use semantic colors if:

You want to highlight an important status.
You want to validate fields using form field validation.
Your app needs message handling.
You want to use the value states for a control.

Do not use semantic colors if:

The color has no meaning and is used only for decoration.
You want to use colors in an industry-specific context, where the meaning of the colors differs from the standard semantic meaning. Use the industry-specific colors instead.

Use industry-specific colors if:

You want to use a color based on industry conventions (for example, when the meaning of a color is defined in an industry standard).

Do not use industry-specific colors if:

The color has no meaning and is used only for decoration.
No special industry color conventions apply. Use the standard semantic colors instead.

Overview

Semantic Colors

SAP Fiori has five semantic colors that are associated with the following predefined value states:

Regular (neutral)
Good (positive)
Warning (critical)
Bad (error)
Information (highlight)

Semantic checkbox states

Industry-Specific Colors

SAP Fiori has 10 generic indication colors that are intended only for industry-specific use cases. You can associate these colors with a specific meaning in a given industry context (for example, to reflect industry standards).

Each application must clearly communicate the meaning of each color. In addition to using a color, you must also provide a text, such as an object status. All colors require a corresponding descriptive text for accessibility purposes.

The indication color palette is supported exclusively by tables and the object status.

Object status with five industry-specific colors

Object status with three industry-specific colors

When To Use Which Semantic Color

Only use a semantic color if you need to convey the meaning defined for that color. This section looks at each semantic color in turn, and offers guidance on when to use each one.

Regular (neutral)

Use this color as the regular, neutral state of all UI elements.

Use the regular (neutral) color if:

You want to use the default of a UI element.
There is no reason to use another value state.
You want to indicate a neutral object status.
A message contains non-critical, additional information for users.

Radio button, step input, and input in regular state

Good / Positive

This color stands for a good, positive situation, or for the successful completion of a task.

Use the good/positive semantic color if:

You want to highlight a good or positive status.
A message contains information about a process that was finalized without any issues. Users need this information later on (for example, to copy values to another app).

To indicate a successfully completed process, a short notification is enough. In this case, use a message toast and not the good/positive semantic color.

Radio button, step input, and input in positive state

Warning / Critical

This color indicates a critical situation or warning.

Use the warning/critical semantic color if:

You want to highlight a critical status.
A minor problem has occurred. The user can carry on working, but might run into an error later on.
The current mode or page can be finalized, but doing so might lead to an error later on.
The user input was validated and a minor problem occurred. The user can continue without fixing the problem, but might run into an error later on.
A message contains information about a warning.

Radio button, step input and input in warning state

Bad / Error

Use this color for errors, or to indicate a bad or negative status or consequence.

Use the bad/error semantic color if:

Something bad has happened, or is about to happen. The issue requires the user’s attention. Until the issue is resolved, the user can’t carry on working.
You want to indicate that a value has caused an error.
The user needs to be prevented from finalizing the current mode or page.
The user input failed a validation, and the problem must be fixed before the user can continue.
A message contains information about an error.

Radio button, step input and input in error state

Information

Use this color for an information state.

Use the information semantic color if:

You want to draw attention to a control for an important purpose, such as visualizing the recommendations from intelligent systems in input fields.
You want to highlight newly added items, such as a new table row.

Don’t use the information color if you want to highlight an information text. The blue text color is explicitly reserved for links. Use bold or italic formatting instead.

Radio button, step input and input in information state

Using Industry-Specific Colors

There is no predefined meaning for the individual colors in the generic palette. If you want to use one or several colors from the industry-specific color palette in your application, proceed as follows:

Define the meaning for each color you want to use.
Whenever you use an color, provide an additional text indicator (such as an object status) to ensure that the text is clear and accessible.
Once you have defined the meaning for a color, use the color/meaning consistently within your application.

Color Overlap

By default, some colors are the same in the semantic palette and the industry-specific color palette (such as red, orange, green, and blue). This is intended. However, the two color palettes can be themed independently, which means that end users might not see the same colors in both.

No Palette Mix

Some UI elements support both the semantic color palette and the industry-specific color palette. However, you can only use one color palette at a time. It is not possible to mix different colors from both palettes.

Color Hierarchy

If an UI element would have multiple semantic or industry-specific color statuses at the same time, the control may need to determine an “overall color” at first.
In this case, the overall color is based on the color hierarchy: colors higher up in the hierarchy take precedence over those lower down. Note that there is only one hierarchy for both semantic colors and industry-specific colors.

Color hierarchy

Styles

The semantic colors and industry-specific colors are themeable.

Resources

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

Elements and Controls

Quartz Light Colors (guidelines)
Belize Colors (guidelines)
UI Element States (guidelines)
Form Field Validation (guidelines)
Message Handling (guidelines)
Object Display Components (guidelines)

Implementation

Object Status (SAPUI5 samples)
Input with Different Value States (SAPUI5 samples)

Illustrated Message

An illustrated message is a combination of a solution-oriented message, engaging illustration, and conversational tone to better communicate an empty state than just a message alone.

An illustrated message turns a situation (even a negative situation) into a better experience for your users, while ensuring consistency. Through their human-centered approach, illustrated messages help to create a deeper connection with users by making them feel understood, valued, and respected.

When to Use

Use an illustrated message if:

You want to improve the user experience for one or more empty states or message states in your application.

Do not use an illustrated message if:

You want to use the illustration for decoration, as a simple image, or for something else. If you want to display a person or a product image, use the avatar. If you want to display an image, use the image control.
You want to display problem-oriented messages. Reconsider and check out the message handling guidelines and the UI text guidelines for messages.

Generic illustrated message

Components

An illustrated message consists of the following parts:

Illustration set (highly recommended)
Message headline (mandatory)
Message description (mandatory)
Call to action (optional)

Anatomy of an illustrated message

Illustration Set (1)

An illustrated message has a set of four UX illustrations per use case: dot, spot, dialog, and scene. Each illustration has a different size and level of detail. The illustration sizes are used at different breakpoints to ensure that the illustration is always appealing, regardless of the container size.

The illustrations help clarify the situation and add personality. It’s essential that the illustration is appropriate for the use case and the container you’re using (such as a dialog or card), and that similar use cases are handled consistently. The control automatically comes with illustrations for a set of dedicated use cases (see information box). You can use these illustrations if your use case is the same.

Each illustration is a themeable SVG file. Illustrations are generally non-interactive. They do not require a tooltip or an alternative text.

Illustration set with all four illustration sizes: dot, spot, dialog, scene

Information

The following use cases are already covered by the illustrated message control:

Before Search
No Activities
No Data
No Email
No Entries
No Notifications
No Saved Items
No Search Results
No Tasks
Unable to Load
Unable to Upload

Check out all use cases in the SAPUI5 samples.

Message Headline (2)

The headline explains the reason for the empty state, preferably in a single line. Use the headline to convey the essence of your message in simple, engaging language.

Write the headline in sentence case without an ending period (.) or other punctuation. Exceptions include situations where you may want to emphasize the headline with an exclamation mark (!) or question mark (?).

If you are using one of the standard use cases, you can refine the default text to tailor it to your specific app use case.

Message Description (3)

The description adds details and tells the user what to do next, in three sentences or less. Write the description in sentence case with proper punctuation. You can also set links in the description (property: enableFormattedText).

If you are using one of the standard use cases, you can refine the default text to tailor it to your specific app use case.

Call to Action (4)

If there is a clear next step, include a call to action, ideally in the form of a button.

Adaptiveness

Default Behavior

By default, the illustrated message control adapts its appearance according to the size of the container in which it is placed (such as a dialog or card).

Fixed Sizes

Alternatively, you can set a fixed size for the illustrated message. This is only recommended in use cases where a page has multiple empty states in various controls and the illustrated message container is always rather big, resulting in several larger illustrated messages on one screen and hence a lot of unnecessary scrolling. For example, long object pages can contain several UI elements that are all initially empty. Be aware that the illustrated message remains fixed in such cases, also when the user resizes the window.

The illustrated message control offers the following predefined fixed sizes:

Base – Smallest size. Not enough space to display an illustration.
Dot – Size for very small containers, such as tiles, cards, and table cells.
Spot – Size for small containers, such as cards.
Dialog – Size for medium-sized containers, such as dialogs.
Scene – Size for large controls, such as tables and empty states for an entire screen.

Base size in a cell

Dot size in a small card or tile

Spot size in a card

Dialog size

Scene size in an empty page

Examples

Here are some examples of how illustrated messages can enhance the user experience for different empty states.

Empty state - Empty calendar

Empty state - File upload

Empty state - Search

Empty state - Page not found

Empty state - Error page

Empty state - No results

Top Tips

Turn a negative event into a positive one

Take time to design and write a solution-oriented message. Be precise in your wording and take care to use appropriate illustrations.

Reflect on old message habits. Have a look at the “Don’t” example. Why doesn’t this message work?

The image ignores cultural considerations, doesn’t follow the illustration guidelines, and is unlikely to delight the user.
The message text is problem-oriented and not helpful. It leaves the user alone with the problem and is likely to trigger negative emotions.

Ideally, a negative event in a software product doesn’t generate negative emotions. A well-designed illustrated message that leaves users feeling understood and valued can result in a neutral or even positive feeling. Remember that users will benefit from thoughtfully crafted illustrated messages every time they encounter them – perhaps even daily.

Don't

Unhelpful, problem-focused message with negative imagery

Do

Helpful message with appropriate illustration and possible solutions

Always write a coherent, solution-oriented message

Make sure that the illustration, message, and call to action work together as one to clarify the situation. Always provide a message. Never use an illustration without a message. A message combined with an illustration is more powerful than a message alone.

Don't

Illustration without a message and unrelated to the action

Do

Matching message, illustration, and action

Tailor your message to your use case

Always ensure that the default text fits in the context. If not, replace it or make it more precise.
Example:
Default text: No results found / Try changing your search criteria.
Adapted text (supplier table used with a filter bar): No suppliers found / Try adjusting your filter settings.
Recommended: Replace generic terms like “data” and “object” with your specific business object.
Example:
Default text: There’s no data yet / When there is you’ll see it here.
Adapted text: There are no orders yet / When there are, you’ll see them here.

Additional tips

Never use other icons, images, or illustrations for an illustrated message. Always follow the guidelines on using UX illustrations.
Don’t use the predefined illustrations for other use cases than the ones they were designed for. This would dilute the strength and recognizability of the illustration in the defined use case.

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.

Don't

Don't use a responsive table as a form

See the table overview to decide which SAP Fiori table is most suitable for your needs.

Responsiveness

The responsive table is optimized for viewing one line item at a time with no scrolling or only vertical scrolling, irrespective of the display width.

On smartphones, only the most important data remains in the one-column or two-column table, while all other data is moved to the space between two item rows, known as the “pop-in area”.

In this area, data for the corresponding cell is provided as a label/value pair. The label is defined by the column header, and the value is taken from the corresponding cell. Labels can be displayed next to the value or above the value.

Within the pop-in area, the label/value pairs can be displayed in the following ways (sap.m.Table, property: PopinLayout):

Block: Label/value pairs are listed one below the other.
GridSmall: Label/value pairs are displayed next to each other in equally spaced grid cells. An additional column is shown for each 13 rem of available width (208 px with default browser settings). If the number of grid cells exceeds the available width, the grid cells wrap. On S size, this layout transforms automatically to a block layout.
GridLarge: The display logic is the same as for GridSmall,, but grid columns come with a larger minimum width (26 rem instead of 13 rem).

In all layouts, you can show the labels next to or above (recommended) the corresponding data.

The responsive table uses all the available space, and does not provide any padding. If there is space around the table, it comes from the spacing defined for the surrounding layout container.

Information

The GridSmall and GridLarge layouts are not available in all browsers. If the chosen layout is not available, it is automatically changed to Block layout.

Responsive table displayed on a smartphone (size S)

Responsive table displayed on a tablet (size M)

Responsive table displayed in compact mode on a desktop computer (size L)

The responsive behavior is optional. If it is not used, the responsive table 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.

A typical responsive table

Hide the information column for a width smaller than 570 px.

Hiding the information column

Move the column “vendor” to the pop-in area for a width smaller than 460 px (sap.m.Column, properties: demandPopin, minScreenWidth).

Moving the vendor column to the pop-in area

Move the column “limit” to the pop-in area for a width smaller than 350 px (sap.m.Column, properties: demandPopin, minScreenWidth).

Moving the limit column to the pop-in area

Move the column “price” to the pop-in area for a width smaller than 270 px (sap.m.Column, properties: demandPopin, minScreenWidth).

Moving the price column to the pop-in area

If you still need to support smaller screens, values can be moved below the corresponding labels inside the pop-in area. In these examples, this happens for a width smaller than 220 px (sap.m.Column, property: popinDisplay).

Pop-in area: Moving the data below the labels

Example for GridLarge Layout

A more complex responsive table.

A more complex responsive table (full screen without pop-in content)

In this example, the Average Occupancy Rate and Available In columns move to the pop-in area if the screen width is less than 1900 pixels.

GridLarge layout - 'Average Occupancy Rate' and 'Available In' columns move to the pop-in area

If the width is less than 1500 pixels, the Average Stay column moves to the pop-in area.

GridLarge layout - 'Average Stay' column moves to the pop-in area

If the width is less than 1100 pixels, the Description column moves to the pop-in area. Since all four columns in the pop-in area do not fit into one row, the pop-in content wraps.

GridLarge layout - 'Description' column moves to the pop-in area

If the width is reduced even further, the Details column moves to the pop-in area. On this narrow screen, only one column fits into one pop-in row, so it looks exactly like the block layout.

GridLarge layout - 'Details' column moves to the pop-in area

Layout

The optional title bar consists of the title of the responsive table, an item counter, variant management, and the toolbar.

The filter infobar appears when the responsive table is filtered, and shows information on the filter settings.

The column header shows the label for each column. In addition, it allows the user to resize the column.

The collection of items, or rows, occupies the main part of the responsive table.

You can add aggregation information (such as totals) on the table footer.

A More button can be shown if you do not want all items to be loaded at the start (known as “lazy loading”). Ideally, you should use scrolling to load more items instead of choosing the More button.

Schematic visualization of the responsive table

Components

The title bar contains the title of the responsive table, an item counter, variant management, and the toolbar.

The toolbar can contain entry points for the view settings dialog and the table personalization dialog, as well as view switches in the form of a segmented button, and buttons for Add, Edit, and other actions.

Beneath the toolbar, display a filter infobar (which itself is a special toolbar) if the responsive table is filtered.

To format within items, apply the guidelines for formatting data. Controls commonly used inside items are the object identifier and the object number. For more information about these controls, see object display components.

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

The More button loads more items to the front end if not all items have yet been loaded.

Components of the responsive table

Behavior and Interaction

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

Table Level

Scroll

The height of the table is defined by the number of items it contains. It does not have a scroll container on its own, but is scrolled together with the app (in contrast to the grid table and the analytical table).

If the table works in “growing” mode, it only loads a few items at first. Additional items are only loaded (and rendered) on request. The “request” can either be triggered by scrolling (preferred), or by clicking the More button.

Same table, different number of items

When the user scrolls, the title bar, column headers, and filter infobar can stick to the top of the surrounding layout container (sap.m.Table, property: sticky).

Information

The “sticky” feature comes with some limitations:

It is not available on all browsers. In non-supporting browsers, the corresponding areas (title bar, column headers, filter infobar) are not fixed on top of the surrounding layout container while scrolling.
Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the table is placed within the object page.
If focus is set to a fixed column header, the table is automatically scrolled to top.

Sticky table title and sticky column header

Merge Duplicates

To simulate the behavior of row spanning, you can merge cells of consecutive rows inside one or more columns automatically if they contain the same value (sap.m.Column, properties: mergeDuplicates, mergeFunctionName).

Use the merge feature if you expect the column to contain duplicate entries, and it makes sense to group them. In the example screenshot, the Supplier, Product, and Dimensions columns reflect a hierarchical structure: Suppliers have products, which in turn have dimensions. Because suppliers typically have multiple products, merging duplicate entries for the supplier column makes the table easier to read. Note, however, that when the user sorts the table by another field, the hierarchy changes and the merged items are regrouped accordingly.

Do not use the merge feature:

If duplicate entries are not part of the design. If consecutive table rows happen to have the same values at runtime, this alone isn’t a valid reason to group them.
If the corresponding column can contain blank cells. Otherwise, it is cumbersome to differentiate between blank values and merged values.

Supplier column merges duplicates in consecutive rows

Merged columns with multiselection

Select

A responsive table can have one of the following selection modes (sap.m.Table/ sap.m.ListBase, property: mode):

None: Items cannot be selected (sap.m.ListMode.None).
Note: Line items can still use the sap.m.ListType “navigation”, which allows click handling for specific line items. Only use this option if the click triggers navigation to a corresponding details page.
Single select master: One item in the responsive table can be selected. Items are selected by clicking the whole row. The single select master mode has no obvious visual cues, such as checkboxes or radio buttons. It only provides a light blue background for the selected state. Because of this, it can barely be differentiated from tables without selection (mode: None). Single select master is the preferred mode for single selection (sap.m.ListMode.SingleSelectMaster).
Single select left: One item in the responsive table can be selected. For this, the responsive table provides radio buttons on the left side of each line item. This mode is not recommended (sap.m.ListMode.SingleSelectLeft).
Multi select: Users can select one or more items using the checkboxes on the left of each line item. The Shift key can be used to select a range. Users can (de)select all items using the Select All checkbox to the left of the column header (or CTRL+A). Select All should (de)select all items that the user can reach by scrolling. (sap.m.ListMode.MultiSelect).
Another multi select variant is to not provide a Select All option, but just a Clear All check box in the same place (property: multiSelectMode, value: ClearAll).

Keyboard: If the focus is on a row, the space bar selects the corresponding item.

Responsive table without selectable items

Single select master

SIngle select left, with radio buttons. Use only if row clicks are used for something else.

Multi select with 'Select All' checkbox

Multi select with 'Clear All' button

Group

When items are grouped, a group header is displayed. The group header is not interactive.

Group headers

Show Aggregations

Show aggregations (such as totals) on the table footer (sap.m.Column, aggregation: footer).

Don’t show aggregations in “growing” mode. In “growing” mode it isn’t clear which values are being aggregated; only the items currently loaded in the front end, or all items.

Table footer displays aggregated total

Load Items

When the responsive table fits the general requirements for your use case, always consider ways to reduce the amount of data loaded in the responsive table with, for example, filters, graphics, aggregation of information, and navigation. Keep in mind you should use it only to display moderate amounts of data, including factors like number of items and content complexity.

To show more than 100 items, use the “growing” mode (sap.m.Table/ sap.m.ListBase, properties: growing, growingThreshold, growingScrollToLoad, growingTriggerText). The “growing” mode allows the user to load only the first few items. Additional items are only loaded (and rendered) on request, which improves performance. You decide whether the user triggers the request by scrolling (preferred) or by clicking the More button.

If you use the More button, show the number of items already loaded and the total number items below the More text, if possible.

Do not show aggregations in “growing” mode. Also, do not display an item count on the table toolbar if “growing” mode is used. Use the count on the More button instead.

Guidelines

If you expect users to work with large amounts of data, use the grid table because it is optimized for handling large data sets.

The growing mode will only help to reduce the amount of data loaded at once but the limits to the overall amount of data still apply.

Load on scroll

Column Header Level

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

Resizing Columns

If you implement column resizing, users can resize the columns as follows:

Mouse interaction: The user drags the separator line between two columns. Double-clicking the line optimizes the column width based on the length of the currently visible data and the label of the column header.
Touch interaction: As for mouse interaction, but with a larger target touch area.
Keyboard interaction: When the focus is on the column header, Shift+Right increases the width of the focused column. Shift+Left decreases the width.

When a column is resized, the other columns can keep their original width or adapt their width. This depends on the column width settings:

If column widths are set in pixel-based units (px, em, rem), the resized column is adapted and the columns that follow are moved accordingly. The width of all the other columns is not affected. If the visible columns don’t use the full width of the table control, empty space is added. If the visible columns exceed the width of the table control, one or more columns move to the pop-in area.
If all column widths are set as a percentage or as “auto”, resizing one column might also result in automatic resizing of some or all other columns. The position of the resized column might also be affected. This ensures that the full table width is used and no white space is added.

Developer Hint

To enable resizable columns, implement the plugin:
sap.m.plugins.ColumnResizer.

Resizing a column

Line Item Level

Delete Single Item Rows

To delete single item rows, use the table in the mode “delete” (sap.m.Table/ sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This adds Delete buttons to each line item. Clicking this button triggers the deletion of the corresponding line item. (Keyboard: If the focus is on the row itself, the Delete key can be used to trigger the Delete button.)

Do not use this mode if deleting multiple lines at once is the preferred use case.

Delete is a mode of the responsive table and therefore cannot be used together with single selection or multiselection.

Responsive table in 'Delete' mode

Highlight an Item

To highlight an item, use the “highlight” indicator (sap.m.ColumnListItem, properties: highlight).

Highlighted item

Navigate

To allow navigation from a line item, use an item with the type “navigation” (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This creates an indicator at the end of the line (“>”) and the entire line item becomes clickable (keyboard: if the focus is on the row itself, the Enter key triggers navigation). If the user clicks on the line, navigate to a new page containing line item details. In rare cases, you can also use the navigation mode for category navigation, without navigating to another page.

By contrast, clicking an interactive control within a line item does not trigger the navigation event. Instead, the corresponding control handles the click event.

If no navigation is possible, set sap.m.ListType to “inactive”.

“Navigation” is a list item type and therefore cannot be used together with “edit”, or in combination with click events for the entire item (“active”).

Navigation indicator

Indicate Navigated Item

When multi-selection 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 only (multi-selection table with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.ColumnListItem, property: navigated).

Navigated item

Edit Line Items

To allow editing for a line item, set sap.m.ListType to “detail” within the corresponding item (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive). This will create an Edit button at the end of the line. Clicking the button triggers the edit event (keyboard: If the focus is on the row itself, the F2 key triggers the Edit button). Use this event to switch the corresponding line item to edit mode.

Edit is a list item type and therefore cannot be used together with “navigation” or in combination with click events for the entire item (“active”).

Edit button

Click an Item

Items as a whole can be clickable. An event is fired by clicking on the item (anywhere where there is no interactive control inside the item). Apps can react on the event, for example, by opening a dialog (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Active or sap.m.ListType.DetailAndActive).

Active elements do not have a visual indication and can therefore not be differentiated from non-active elements.

Active is a list item type and can therefore not be used together with “navigation” or “edit”. In addition, “active” uses the whole item as a clickable area and therefore cannot be used together with a single-selection table.

Active element

Drag and Drop

One or several items can be repositioned within a table or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop

Whole item as drop target

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column). Context menus can be implemented for a specific table or row.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or Shift+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Responsive table with a context menu

Cell Level

Showing Information

In contrast to traditional tables (such as the analytical table or the tree table), a cell can contain more than just one line of text.

Several lines of text within one cell

Add Controls

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

Controls inside cells

Any control can be placed inside cells

A cell can contain more than one control and more than one data point.

With the View Settings dialog, users can sort, filter, and group by each of these data points.

Several controls per cell

You can also have different controls in different rows in the same column. This could be the case if one item is locked, but another item is in edit mode, for example.

Different controls per column

Guidelines

Responsiveness

In most cases, the auto pop-in mode is sufficient. If you need to optimize further, first try to adapt the columns to influence the automatic behavior (sap.m.Column, properties: autoPopinWidth, importance). For example, set the priority for the two or three most important columns to “High” (identifying column, key attribute).

While the pop-in layouts GridLarge and GridSmall make better use of the available width, they also only look good with content that is specifically designed for these pop-in layouts. If you have text-only tables with only one value per column, use the Block layout (sap.m.Table, property: popinLayout).

Place the column header labels in the pop-in area above the corresponding values (sap.m.Column, property: popinDisplay, value: Block). This avoids alignment issues with different content. Be aware that the labels get top-aligned with the adjacent content.
Only place the label next to the corresponding value under the following conditions (sap.m.Column, property: popinDisplay, value: Inline):

The values are text-only (no input fields, icons, images, micro charts, and so on)
The available space is at least the double the width of size S.

This avoids truncation or “over-wrapping” of the labels and content.

If a column does not have a column header text (for example, if it always contains the same button with its own label), do not show the header text as a label in the pop-in area either (sap.m.Column, property: popinDisplay, value: withoutHeader). If you forget this setting, you will see an empty space followed by a colon (“:”).

Information

The GridSmall and GridLarge layouts are not available in all browsers. If the chosen layout is not available, it is automatically changed to Block layout.

Table Title

Implement the table title by using a title control in a toolbar.

Use a table title only if the title of the table is not indicated in the surrounding area. Do not use a table title if it simply repeats text that is already above the table. For example:

A pricing conditions table is the only control on a tab labeled Pricing Conditions.
A section or subsection on an object page contains only one table.

Use a table title if you need the item count, table toolbar, or variant management. To avoid repeating text, feel free to use generic text as a table title, such as Items.
Exception: If the surrounding area contains the table title, and both the item count and toolbar can be added to the surrounding area, no additional table title is needed.
Example: An object page (sub-)section contains only one table. In this case, add the item count and the table toolbar to the (sub-)section header.

Developer Hint

Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table.

If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

If you use a table title, show either a title for the table, with or without variant management, or an item count in the following format:

Items (2,534)

The item count in the table title includes all the visible items that a user can reach by scrolling. Group headers are not included.

Remove the item count in the table title if there are zero items. Do not use an item count together with “growing” mode.

If possible, keep the title bar sticky (sap.m.Table, property: sticky).

Table title with item count

Selection

For single selection cases, use the selection mode “single select master”. This is the recommended single-selection mode for list-detail scenarios within the flexible column layout. If you use it there, do not show a “navigated” indicator.

In rare cases, you can also use the click area for the row for another purpose (for example, to open dialogs). As a result, the click area cannot be used for selecting the row. In these cases only, use the “single select left” selection mode to offer a radio button as an additional click area for each row. To avoid confusion, make sure that the first data column does not contain radio buttons in the default delivery.

For all single selection modes, make sure that one item is initially selected. Otherwise, the user cannot return to the initial state. A selected item can only be deselected by selecting another item.

In multiple selection mode:

Prefer Select All over Clear All
Use Clear All only for tables with a large number of items (more than recommended above), where loading all items to select them would harm performance.
To avoid confusion, don’t show checkboxes in the first data column in the default delivery.
Make sure that the Select All checkbox (de)selects all items the user can reach by scrolling. This is only possible if all items are rendered.
Never disable the selection checkbox. If an action can’t be performed on a specific item, inform the user after the corresponding action has been triggered. For more information, see Enabling/Disabling Actions.

Don't

Single selection left - Don't show radio buttons in the first column in the default delivery

Don't

Multiple selection - Don't show checkboxes in the first column in the default delivery

Do

Use the selection mode "single select left" if clicking the row is used for something else (such as navigation)

Do

Use the selection mode "single select master" in all other single selection cases

Developer Hint

Select All is only applied to items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded, such as items added via lazy loading with growingScrollToLoad. This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

To process all items, listen to the selectionChange event and to its selectAll flag. This indicates whether the Select All checkbox was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

Loading Data

To indicate that the table is currently loading items, use the busy state. (sap.m.Table, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Table in busy state while loading data

Errors and Warnings

To indicate that the table contains items with errors or warnings, show a message strip above the table. On the message strip, provide information on errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

To indicate an error in a single row, see Item States below.

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

Developer Hint

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

Table containing errors

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.

Don't

Do not distribute just a few columns across the full width

Do

Use a fixed column width instead

Column Headers – Best Practices

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

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

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.

Do

Wrap column headers if columns are not resizable

Do

Truncate column headers if columns are resizable

Column headers (sap.m.Column, aggregation: header) usually contain links or text-based controls.

Column headers can also contain other kinds of SAP Fiori controls. However, the column header cannot be aligned vertically, making it difficult to use many controls in the column header. Using other kinds of controls also creates problems with pop-in behavior and could thus lead to accessibility issues. Therefore, exercise caution when using them in a column header.

Accepted: Link as column header text (rarely used)

Accepted if responsiveness is taken into account: Text plus search field

If a column cell contains several fields, use an umbrella term in the column header (such as Address for fields like Street, ZIP Code, and City).

For text and ID fields, use a generic label (for example, Employee for Name and ID).

If none of these are possible, separate the labels with “/” (for example, Name / Status).

For boolean values, such as checkboxes, find a descriptive text for the column header.

Horizontal Content Alignment

For alignment of cell content, follow the guidelines below (sap.m.Column, properties: halgin, valign, sap.m.ColumnListItem, property: VAlign). Align the column header horizontally according to the content of the cell.

Exception: Secondary information in a column always follows the alignment of the main information.

Left-Align

Left-align: Text, IDs, phone numbers, URLs, passwords, and email addresses.

Left-align text

Left-align: Status information

Left-align status information

Right-Align

Right-align: Dates and times (to ensure comparability for most formats and locales)

Right-align dates

Right-align: Numbers and amounts, except IDs, to ensure figures are comparable

Right-align numbers

Center-Align

Center-align: Icons, images, and avatars

Keep the column name for center-aligned columns as short as possible to avoid excessive white space between columns. Alternatively, you can leave the column header empty on the visual UI, and use the invisible text control to provide information on the column content for screen reader listeners.

Align buttons with the content hierarchically

Always place buttons directly next to their content. Do not add an additional column for buttons. If you have more than one button, display them next to each other. Order the buttons based on importance. The most important button is on the left, the least important on the right. If there is not enough space to display them all in one line, move the buttons from the right onto the next line one by one. Do not use more than two buttons per line item.

Vertical Content Alignment

Top-align where possible to facilitate reading the content on one line.

Do not use top-alignment if it results in a peculiar layout. This usually happens when controls that need more vertical space are combined with text-only controls, such as input fields. In this case, try center-alignment instead and fine tune it until the layout fits.

Do

Use top-alignment where possible

Don't

Don't use top alignment if it doesn't make sense

Content Formatting

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

As a key identifier of an item, use an object identifier. Show the key identifier in the first column. For more information, see object display components.

If the table width is small, do not hide this column or move it to the pop-in area.

Object identifier

Strings with IDs: If the responsive table contains more single-line data, show the ID in brackets after the corresponding string.

This minimizes the line height.

For items with a small line height, place the ID in brackets after the corresponding string

If displayed as a link, use the whole text as the link

Strings with IDs: If line height is already large, show the ID below the corresponding string. Use the object identifier to do so.

For items with a large line height, place the ID below the corresponding string

Is displayed as a link, use only the first line as the link

If there is more than one key identifier (for example, First Name and Last Name), display these columns first and show the values in bold text.

Several key identifiers

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

For status information on text: If the status is actionable, add a transparent icon button next to the text.

Semantic colors on text

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

For example, use text.

Do

Wrap text

Don't

Don't truncate text

For editable content, use input fields and other interactive controls within the table cells. If you need to offer edit mode, change your text controls (labels, text, and links, to input fields or other appropriate controls) as soon as you switch to edit mode, but not before.

You can do this by changing the control or, in more complex cases, by exchanging the whole responsive table.

Interactive controls – Inline

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

Leave empty fields blank

Numbering Items

If the item number has four digits/letters or less and is equally important as the corresponding description, concatenate the item number with the description and show it in one column.
If the item number has five digits/letters or more, or if it is more important than the corresponding description, for example, when no description is available, use a separate column for the item number.
If the item number is more like an ID in regards to its description, use ID formatting, like Description (ID).

For short numbers, add the item number to the description

Flag and Favorite

Place the flag or favorite marker in the first column (in the default delivery). To change the settings, users need to drill down into the object itself.

Item marked as a favorite

Empty Tables

Try not to display an empty responsive table. If there is no way around this, provide instructions on how to fill the table with data (sap.m.Table/ sap.m.ListBase, properties: showNoData, noDataText).

Examples:

If a table is initially empty, provide at least a basic text:
No items available.
Overwrite this whenever a hint can be provided on how to fill the table with data.
If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
To start, set the relevant filters.
If a table is used together with a filter bar and the filter does not return results, use the following text:
No data found. Try adjusting the filter settings.

Adapt the texts above if:

The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
The standard text is misleading (for example, if the data is filled based on a list-detail pattern instead of filter settings).

Remove the item count in the table title if there are zero items.

Provide meaningful instructions

Displaying Boolean Values

If a column contains Boolean values, such as “Yes” or “No”, show a read-only checkbox next to the texts.

The supplementary checkbox makes it easier for users to see at a glance which items are “true” (checked) and which are “false” (unchecked).

Developer Hint

Use sap.m.checkbox with the Horizon theme and set the editable property to “false” to get the read-only variant. Add the checkbox next to the existing text value. The text itself should remain unchanged.

Avoid showing only text for Boolean values

Boolean values with read-only checkboxes for easier scanning

Item States

To show that an item is unread, use the corresponding flag (sap.m.Table, property: showUnread, sap.m.ColumnListItem/ sap.m.ListItemBase, property: unread). This shows most of the content in bold font.

An unread item

To show that an item has been modified, for example, within the global edit flow, add the string (Modified) at the bottom of the column that identifies the line item.

A modified item

To show that a modified item contains an error (for example, within the global edit flow), add the string (Contains errors) at the bottom of the column that identifies the line item. To do this, use an object status control with the error state (sap.m.ObjectStatus, property: state, value: sap.ui.core.ValueState.Error).

In addition, highlight the row accordingly (sap.m.ListItemBase, property: highlight). A row with errors should be highlighted in all use cases – for example when the field is visible in the row in edit mode.

A modified item with an error

To show that an item is locked, use a transparent button with the corresponding icon and the text Locked by [Name] at the bottom of the identifying column. The user can click the button to open a quick view of the person.

A locked item

To show that an item is in a draft state, use a transparent-style button with the text Draft at the bottom of the identifying column. The user can click the button to open a popover showing the timestamp of the last change.

Item in draft state

Show only one state at any one time.

Highlight Items

To show that an item needs attention, you can show a highlight indicator next to the item. The highlight indicator can indicate:

A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It doesn’t tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted items using status colors

Highlighted items using industry-specific (indication) colors

Numbers and Units

If the following conditions all apply, show the unit of measurement in the column header:

The unit of measurement is the same for all rows
A single cell contains only one amount with the unit of measurement
The column header does not scroll away

In all other cases, show the unit of measurement together with the corresponding amount within the row.

Show the unit of measurement in the same column as the corresponding amount.

For numbers with units, show the correct formatting by using the object number control.

Object number

For the most important number with its unit, show the correct formatting by using the object number control and the emphasized flag.
Exception: If all numbers are of equal importance, emphasize none of them.

If the table width is narrow, do not hide this column or move it to the pop-in area.
Exception: If the column containing the object identifier and the column containing the key attribute do not fit together on the screen, move the column containing the key attribute to the pop-in area.

Object number (emphasized)

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.

Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within the table, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop targets in between items

Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on values in a column, the dropped item needs to take on the value of the target group for the corresponding column. If this is not wanted, do not allow users to rearrange items in grouped tables.

Example:
A table is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Don't

Don't combine rearranging items with grouping, unless you know exactly what you're doing.

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

The context menu can be triggered for the whole table or per row.

Actions

To trigger actions on multiple items, use a multiselection table (sap.m.Table, property: mode, value: sap.m.ListMode.MultiSelect), and offer the corresponding actions on the table toolbar. Keep the table toolbar sticky (sap.m.Table, property: sticky).

Do not offer actions for multiple items if the table is expected to have fewer than 10 items in most cases.

To trigger actions on a single item only (sap.m.Table, property: mode, value: sap.m.ListMode.SingleSelectMaster):

Show the actions on the table toolbar.
In rare cases, show the actions within the line item. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. In this case, show the action trigger near the content to which it belongs. Do not add a specific column for actions. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.
Don’t bundle inline actions that don’t belong together under an unspecific label, such as Misc, Actions, … , or similar.

Do

Inline actions

Don't

Don't combine unrelated inline actions

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

Delete: Use “Delete” table mode (sap.m.Table/ sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This places a Delete button at the end of each row.

Delete button

Navigation: Use the “Navigation” column list item type (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This places a Navigation indicator at the end of each row.

Use this to navigate to a new page containing line item details. In rare cases, you can also use this for navigation within the table without navigating to another page.

Navigation indicator

Edit: Use the “Detail” column list item type (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail). This places an Edit icon at the end of each row.

Edit button

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.

For information on enabling and disabling actions, see Enabling/Disabling Actions.

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:

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.
Open a dialog for larger tables with up to 8 editable columns. Save the new item at the dialog level.
Navigate to a new page. This behavior should only be used for very complex scenarios that cannot be handled by a dialog (for example, tables with more than 8 columns). When the user presses Save in the footer toolbar of the create page, navigate back to the table.

Depending on the flow, an item can be in one of three different states:

New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the table. Ignore current sort, filter and grouping criteria to keep the item visible.
Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
- Inline creation: After Save was triggered on the table toolbar or at page level
- Create with dialog: A table showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

In the context of the draft handling new items are not saved on table level, but rather with the entire draft.

For more details, see the guidelines for managing objects (including subarticles).

Add button in table toolbar

New item as first row in edit mode

Saved new item, still highlighted, still the first item

Editable Content

For editable content, use input fields and any other interactive controls within the table cells that meet your input needs.

All SAPUI5 controls can be used.

If you need edit mode, change your text controls, such as label, text, and link, to input fields, or other appropriate controls as soon as you switch to edit mode, but not before.

You can do this by exchanging the control or, in more complex cases, by exchanging the entire responsive table.

For mass editing items:

Provide multiselection (sap.m.Table/ sap.m.ListBase, property: mode, value: sap.m.ListMode.MultiSelect).
Provide an Edit button.
If several items are selected, choosing the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

For details, see mass editing.

View Settings: Sort, Filter, Group

Sort, filter, and/or group settings are handled in the view settings dialog. This dialog can provide any combination of these three settings, including just one setting, such as sort only.

If sorting, filtering, and/or grouping are a common use case in your app, offer one, two, or all three of the corresponding features in one or more view settings dialogs. Note: Do not offer these features if the table is expected to have only a small number of entries (up to 20 in most cases).
If filtering is a main use case, do not offer filtering in the view settings dialog. Use the filter bar instead.

To trigger the view settings dialog, provide several buttons, one for each of these view settings. Each button opens a view settings dialog that contains only the relevant page.

You should always use only the view settings you really need. For example, do not offer grouping if it does not support your use case well.

Using the view settings dialog allows you to define several sort, filter, and/or group settings per column. Therefore, you can sort, filter, and/or group a column with several data points independently by each data point.

Several triggers for the different view settings (sort, filter, group)

Sort

Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the first column in the default delivery. Use the primary data point from this column.

If you offer sorting, offer it for each data point. In other words, allow sorting by both the primary and secondary information in a column. Allow sorting in both directions, ascending and descending. The descending sort order must always be the exact reverse of the ascending sort order.

For each data point, provide a meaningful sort order. For example:

Sort text alphabetically
Sort numbers by their value
Sort status information by the severity of the status:
- Ascending: Sort status information from positive to negative, with neutral last.
- Descending: Sort status information from negative to positive, with neutral first.

Object status sorted ascending, with neutral status last

Object status sorted descending, with neutral status first

- Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
- Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Object status sorted ascending and alphabetically, from positive to negative with neutral last

Object status sorted descending and alphabetically, from negative to positive with neutral first

Filter

To display the current filter state, use the infobar below the table title. Clicking the infobar opens the view settings dialog on the filter page.

Show the infobar only if the filter settings are not shown somewhere else. For example, do not show the infobar for settings taken in the filter bar or in a select placed in the table toolbar.

If the infobar is shown, provide an option to reset all corresponding filters on the infobar.

Keep the infobar sticky (sap.m.Table, property: sticky).

Developer Hint

To display the current filter settings on the infobar, consider using the list formatter (sap.ui.core.format.ListFormat).

Filtered table

Group

To display the current group state, group headers are shown.

On the group header, show the following text (sap.m.GroupHeaderListItem, property: title):

[Label of the grouped column]: [Grouping Value]

Do not use several values on the group header.

Grouped table

If there is no grouping value, show the following text:
[Label of the grouped column]: (Not Available)

This is the case if you have a group of items that don’t have a value for the grouped column.

Grouped table, with missing grouping value

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.

View settings and table personalization icons

Persist the column layout settings. When a user reopens the app, show the responsive table with the same column layout as last defined by this user.

Tables in Object Pages

For more information on the use of tables within the object page, see the Tables section of the Object Page article.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting table data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button

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.

Note

If a user has selected multiple cells to overwrite, but the focus is placed outside of the selection, pasting will follow the guidelines for inline creation as above. This can happen, for example, when the user uses the arrow keys on the keyboard to move the focus.

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.

Elements and Controls

Analytical Table (guidelines)
Feed List Item (guidelines)
Footer Toolbar (guidelines)
Grid Table (guidelines)
Object Identifier (guidelines)
Object Number (guidelines)
Table Personalization Dialog (guidelines)
Table Toolbar (guidelines)
Tree Table (guidelines)
Variant Management (guidelines)
View Settings Dialog (guidelines)

Implementation

Responsive Table (SAPUI5 samples)
Column (SAPUI5 samples)
Column List Item (SAPUI5 samples)
Responsive Table (SAPUI5 API reference)
Column (SAPUI5 API reference)
Column List Item (SAPUI5 API reference)

Grid Table

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.

Grid table shown on a desktop

Grid table shown on a tablet

Layout

Select All – The Select All checkbox selects or deselects all items.
Column header – The column header allows the user to resize and rearrange columns. It also provides access to a menu with column-specific commands.
Selector cells – The selector cells allow the user to select one or more items.
Items – The collection of items, or rows, occupies the main part of the grid table.

Schematic visualization of the grid table

Components

A grid table does not consist of other elements. However, it is common to use a toolbar above the grid table.

The toolbar can contain entry points for the view settings dialog and the table personalization dialog or for the p13n dialog, as well as view switches in the form of a segmented button, and buttons for Add, Edit, and other actions.

Behavior and Interaction

A grid table is quite restricted in terms of its content.

Table Level

Scroll

A grid table allows horizontal and vertical scrolling (sap.ui.table.Table, property: navigationMode, value: Scrollbar).

You can add any number of line items to the grid table, which uses “lazy loading”.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.Table, property: rowHeight).

The grid table is optimized to allow faster scrolling within the first 1000 items.

Scrollbar

Select

Selection Mode

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

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

A non-selection grid table

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

A single-selection grid table

Multiple selection: One or more items can be selected. The grid table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back. The Shift key can be used to select a range.

For multiple selection, you can choose between two variants.

Multi-toggle mode (property: selectionMode = MultiToggle)
Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)

These variants behave differently when the user selects more items than are currently loaded in the front end.

Multi-toggle

In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end (keyboard: CTRL+A). All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

Multi-selection plug-in

If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:

By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
- The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and you can display a corresponding message (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
- If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets. (Keyboard: CTRL+A)
If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.

Information

When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.Table, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

A multiselection grid table

Using the multi-selection plug-in with a limit

Selection Behavior

An item can be selected in different ways, depending on the configuration of the grid table (sap.ui.table.Table, property: selectionBehavior):

Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection grid tables if clicking a row or a cell is not used for anything else.
RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection grid tables if clicking a row or a cell is not used for another purpose, such as navigation.

Compact, Cozy, and Condensed

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

For a desktop, you can also display even more rows on the same screen height by adding the condensed mode in addition to the compact mode. This renders less white space for each item.

Note that the condensed content density has always to be set in addition to compact. Do not use condensed on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable and / or unwanted results, e.g. cozy sized controls in condensed sized containers, missing paddings, etc.

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

Furthermore, condensed mode is not available for Internet Explorer 9. If condensed mode is to be used, please provide a fallback.

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

Column Header

The column header provides the label for the corresponding column and access to the column header menu.

Columns are resized as follows:

Mouse interaction: The user drags the separator line between two columns (sap.ui.table.Column, property: Resizable). Double-clicking the line optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable).
Touch interaction: The user taps the column header to reveal two buttons – one to show the column header menu, and one for resizing. The user drags the latter to resize the column.
Keyboard interaction: The width of the focused column header can be increased via Shift+Right and decreased via Shift+Left.

After resizing a column, the adaptation of the column widths depends on how the column width is set:

If column widths are set in pixel-based units (px, em, rem), the corresponding column is adapted and the columns that follow are moved accordingly. The width of all other columns is not affected.
If all the columns together take up less width than the table control, an empty space is added. In case all columns together take up more width than the table control, a scrollbar appears. (sap.ui.table.Column, property: width)
If all column widths are set in percentage or “auto”, resizing one column might also lead to the automatic resizing of some or all other columns. The position of the resized column might also be affected. This is done to ensure that the whole table width is used and no white space is added. A scrollbar appears only if all or most of the columns shrink significantly. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

Columns can be rearranged by dragging the column header to another position (sap.ui.table.Table, property: enableColumnReordering). Keyboard: the focused column header can be moved by one position in the corresponding direction via Ctrl+Left / Ctrl+Right.

Column header

Opening the column header menu on touch devices

Fewer columns than space available

Column Header Menu

For each column, a menu can contain the following menu items (sap.ui.table.ColumnMenu, property: visible):

Sort Ascending/Descending (sap.ui.table.Column, property: showSortMenuEntries)
Free text filter (sap.ui.table.Column, property: showFilterMenuEntries)
Freeze from the first to the last specified column (sap.ui.table.Table, property: enableColumnFreeze)

For each column, the menu can be replaced by an app-specific menu.

Column header menu

Sort

The column header menu can provide two sort options (sap.ui.table. Column, properties: sortProperty, showSortMenuEntry):

Sort Ascending
Sort Descending

The user selects one of these options to sort the corresponding column accordingly (sap.ui.table. Column, properties: sorted, sortOrder, sortProperty).

Sort settings in column header menu

Filter

The column header menu can provide a search field for entering free text (sap.ui.table.Column, properties: filterProperty, showFilterMenuEntries).

If the user enters a term in the input field and triggers the search by pressing Enter when the focus is on the filter input field, the grid table is filtered by the corresponding column and value (sap.ui.table.Table, properties: filtered, filterProperty, filterValue, filterOperator, sap.ui.table.Column, property: filterType).

Note that the filter may return zero results, in which case, the table might be empty.

General recommendations for filtering:

If filtering is a main use case, choose the filter bar or any other filtering UI over the built-in free text filter.
Only use the free text filter if filtering is a secondary use case and if the filter bar is too heavy.

Free text filter in column header menu

Freeze Columns

The column header menu can provide the option to freeze columns (sap.ui.table.Table, property: enableColumnFreeze). Selecting Freeze freezes all columns up to the one in which the operation was triggered (sap.ui.table. Table, property: fixedColumnCount).

When Freeze is triggered, the menu item changes to Unfreeze for the corresponding column.

Freeze setting in column header menu

Line Item Level

A line item contains a set of cells and provides options for selecting the item.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.Table, property: rowHeight).

Line item

Drag and Drop

One or several items can be repositioned within a table or moved to other UI elements using drag and drop operations (sap.ui.table.Table, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop

Whole item as drop target

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows. Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or Shift+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Grid table with a context menu

Cell Level

A cell provides one data point and can contain one of the following controls:

Button
Checkbox
Combo box
Currency
Date picker
Icon
Input
Label
Link
The following micro charts size XS: Bullet, comparison, stacked bar
Multi-combo box
Multi-input field
Object status
Progress indicator
Rating Indicator
Select
Text
Use only single-line text to keep the same row height. Truncate it if necessary to prevent adverse side effects with vertical scrolling (sap.m.Text, property: wrapping, value: false). Do not wrap.

We recommend against using other controls to prevent issues with alignment, condensed mode, screen reader support, and keyboard support.

Cell

Guidelines

Data Density vs. Complexity

The grid table can be used to display large amounts of data. Unfortunately, the grid table has a high data density and therefore conveys an immediate feeling of complexity.

Only show tables with a lot of data as a last resort. Try the following instead:

Break down the data into manageable chunks and allow the user to navigate or drill down between them.
Use charts with drilldown functionality until the amount of data is more manageable.

Try to avoid horizontal scrolling in the default delivery.

Try to minimize the number of columns, especially if there is a large number of rows.

Table Title

Implement the table title by using a title control in a toolbar.

Use a table title only if the title of the table is not indicated in the surrounding area.

Do not use a table title if it simply repeats text that is already above the table. For example:

A pricing conditions table is the only control on a tab labeled Pricing Conditions.
A section or subsection on an object page contains only one table.

Use a table title if you need the item count, table toolbar, or variant management. To avoid repeating text, feel free to use generic text as a table title, such as Items.
Exception: If the surrounding area contains the table title, and both the item count and toolbar can be added to the surrounding area, no additional table title is needed.
Example: An object page (sub-)section contains only one table. In this case, add the item count and the table toolbar to the (sub-)section header.

If you use a table title, show either a title for the table, with or without variant management, or an item count in the following format:

Items (2,534).

The item count in the table title includes all the visible items that a user can reach by scrolling.

Remove the item count in the table title if there are zero items.

Developer Hint

Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table.

If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

Selection

Single Selection

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

Information

When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

In multiple selection mode (multi toggle), do not show checkboxes in the first data column in the default delivery to avoid confusion.

Don't

Do not add checkboxes to the first data column in the default delivery

Never disable the selection checkbox. If an action can’t be performed on a specific item, inform the user after the corresponding action has been triggered. For more information, see Enabling/Disabling Actions.

Loading Data

To indicate that the table is currently loading items, use the busy state. (sap.ui.table.Table, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Grid table in busy state while loading data

Errors and Warnings

To indicate that the table contains items with errors or warnings, show a message strip above the table. On the message strip, provide information about errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

To indicate an error in a single row, see Item States below.

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

Developer Hint

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

Table containing errors and warnings

Columns – Best Practices

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

The grid table assigns the same width to each column by default. It is recommended that you overwrite this default to provide optimal space for your content (sap.ui.table.Column, property: width).

If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the browser window size results in a scrollbar. After resizing a column, a scrollbar appears if the width of the table is not enough to show all columns. If the columns use less space than available, white space appears on the right side of the last column.

If you define the column width as a percentage, resizing one column affects the width of several or all columns. Text becomes truncated when the browser window size is reduced. This is done to make sure that all columns together fill the space of the table. A scrollbar appears only in case the automatic change of the column widths is not enough for showing all columns. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum.

If you define the column width as “auto”, the behavior is the same as for “percentage”. In contrast to percentage, “auto” distributes the columns equally.

To decide on how to set the column width (pixel / rem / em vs. percent / auto), keep the following in mind:

For tables with only 2 to 3 columns, use pixel-based units. This ensures that on wide screens the values in the columns are not spread over the whole screen, which improves the readability of line items.
For tables with many columns, where a horizontal scrollbar is usually needed, use pixel-based units. This avoids unintended side effects when resizing columns.
For all other tables, use whatever fits your case better.

Be cautious with mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it could also cause even more unexpected side effects when resizing a column. When using percentage-based widths for one or more columns, think of the possibility to not allow end users to resize columns at all.

Optimize the column width for its initial visible content, including the column header texts. If this is not possible (for example, if showing the full texts would result in extremely wide columns), let the texts truncate. End users can change the width of the column to read the full text, as needed.

Maintain a constant column width and avoid adjusting it automatically when the content changes.

Always keep to one line of text. Do not wrap.

Don't

Don't truncate the initial visible content in the default delivery

Don't

Never wrap texts

Column Headers – Best Practices

For each column, provide a label in the column header. In the default delivery, do not truncate the column header texts. Only let the text truncate if showing the full text would make the column too wide. Never wrap the text.

Content Alignment

For alignment of cell content, follow the guidelines below.

Left-align the following: text, IDs, phone numbers, URLs, passwords, and email addresses.

Left-alignment of text

Right-align numbers (except IDs).

This ensures comparability of numbers and amounts.

Right-alignment of numbers

Right-align amounts with currencies to the cell and align them in terms of their respective decimal points.

This ensures that amounts with different currencies are shown correctly, whether these currencies have 0, 2, or 3 decimals.

For aligning to the decimal point, use the sap.ui.uinified.Currency control.

Alignment to decimal point

Right-align dates and times.

This ensures comparability for most formats and locales.

Right-alignment of dates

Left-align status information.

Left-align status information

Center-align icons.

Left-align micro charts.

XS micro charts in condensed mode

Content Formatting

Locale Settings

Be locale-aware: show dates, times, numbers, and so on in the format corresponding to the user’s locale settings.

Key Identifier

Use a bold label or an emphasized link as the key identifier of an item. In the default delivery, show the key identifier in the first column.

Emphasized link

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.

Text and ID in two columns – Allows users to sort and filter both separately

If displayed as a link, use only the text as the link, not the ID

Text and ID in one column – Sorting and filtering is available for either the text or the ID, but not for both

Text and ID in one column - If displaying a link, show the whole string as the link (text and ID)

Truncation

Avoid truncation of typical content in the default delivery (sap.ui.table.Column, property: width). However, since the columns are resizable, do not worry too much if truncation occurs as columns can still be enlarged if necessary.

To prevent adverse side effects when scrolling vertically, all line items must also have the same height. If you need to decide between truncation and different row heights, choose truncation. Do not wrap.

Optimize column width for typical content, not all content

Number of Links

Are there too many links? Use subtle links to avoid a wall of links. Standard links are also emphasized more if they are surrounded by subtle links.

Emphasized links, links, subtle links, and text

Missing Value

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

Leave empty fields blank

Numbering Items

In terms of numbering items:

If the item number is more like an ID with regard to its description, use ID formatting as described above.
In all other cases, use a separate column for the item number.

Add a separate column for the item number

Status

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

For status information on text, use an object status.

Semantic colors on text

Micro Charts

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

Micro charts in a grid table

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

Provide meaningful instructions

Invalid State

To show an invalid state of the grid table within the list report floorplan, show an overlay on the grid table and the corresponding toolbar (sap.ui.table.Table, property: showOverlay). The overlay prevents user interactions.

Use this within the list report floorplan if filter settings have been changed but the grid table is has not yet been updated.

Grid table with invalid data

Item States

To show that an item has been modified, for example, within the global edit flow, add the string Modified in an additional column with the label Editing Status.

In the default delivery, add a column directly behind the key identifier.

A modified item

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.

A modified item with an error

To show that an item is locked, add a transparent-style button with the corresponding icon and the text Locked by [name] in the Editing Status column.

A locked item

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

Item in draft state

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 of measurement in one cell

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.

Number and unit of measurement in two columns

Show the unit of measurment on the column header, if the unit of measurement is the same for all rows. If not, show the unit of measurement within the row.

Drag and Drop

If you offer drag and drop for rearranging items within the table, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop targets in between items

Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

Don't

Do not combine rearranging items with sorting

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items. These are keyboard operable and available on all browsers.

Use drag and drop only in addition to existing visible UI elements

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.

Navigate to details page

Single Cell

To trigger actions on a single cell, create the corresponding click event. Do not use the cell click event if the cell contains interactive controls, such as links.

Add Items

For adding items, place an Add or Create text button on the table toolbar.

Use Create if the button adds a brand new item that doesn’t yet exist on the database.
Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the table, with a visual highlight at the beginning of the row.

Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

There are three options for adding an item. In order of priority (most recommended first), these are:

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.
Open a dialog for larger tables with up to 8 editable columns. Save the new item at dialog level.
Navigate to a new page. This behavior should only be used for very complex scenarios that cannot be handled by a dialog (for example, 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

For editable content, only use the following controls, and only one control per cell:

Only these controls are optimized for all viewing modes of the grid table.

If you need edit mode, change your text controls, such as label, text, link, object status, icons, and currencies, to editable controls as soon as you switch to edit mode, but not before. You can do this by exchanging the controls, for example, from sap.m.Text to sap.m.Input.

For mass editing items:

Provide multiselection.
Provide an Edit button.
If several items are selected, clicking the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

For more information, see Mass Editing.

Interactive controls – In line

View Settings

There are several ways to show Sort and/or Filter settings:

Column header menu: In all cases, show the corresponding settings in the column header menu.
View settings dialog: Simple and more flexible with regard to filter settings. No advantage for sorting.
Table personalization dialog: Provides complex options for sorting items by several levels. It also provides a query-builder-like approach for filter settings. The complexity of the options is also its downside. Use the table personalization dialog for tables with a large number of items.
If filtering is a main use case, use the filter bar. In this case, avoid offering additional filter settings on the table. If you do, the filter settings on the grid table work only on the result set provided by the filter bar.

Always be careful when synchronizing the settings in the dialog with the settings from the column header menu.

Trigger the dialogs in one of the following ways:

View settings dialog: Provide several buttons, one for each of these view settings. Each button opens the view settings dialog on the corresponding page.
P13nDialog: Provide a settings button, which opens the table personalization dialog containing all pages.

Use only the view settings you really need.

Column header menu with view settings

Table toolbar with triggers for view settings dialog

Table toolbar with trigger for table personalization dialog

Persist the user settings: When reopening the app, show the grid table with the same sort and filter settings as last defined by this user.

Sort

Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the first column in the default delivery.

To display the current sort state, an icon is shown in the column header of the most recently sorted column. This icon indicates the sort direction (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

For the default sort settings, sort by the column that identifies the row, which is usually the first column in default delivery.

Column, sorted ascending

Column, sorted descending

The descending sort order must always be the exact reverse of the ascending sort order. For each column, provide a meaningful sort order. For example:

Sort text alphabetically
Sort numbers by their value
Sort status information by the severity of the status:
- Ascending: Sort status information from positive to negative, with neutral last.
- Descending: Sort status information from negative to positive, with neutral first.

Object status sorted ascending, with neutral status last

Object status sorted descending, with neutral status first

- Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
- Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Object status sorted ascending and alphabetically, from positive to negative with neutral last

Object status sorted descending and alphabetically, from negative to positive with neutral first

Filter

To display the current filter state, an icon is shown in the column header of the filtered column (sap.ui.table.Column, properties: filtered, filterProperty, filterValue, filterOperator, defaultFilterOperator, filterType).

Column, filtered

Personalization

Only offer personalization if you need more columns than those that fit on a tablet screen, which is usually five, to fulfill 80% of your main use cases.

Persist the column layout. When a user reopens the app, show the grid table with the same column layout settings as last defined by this user.

Add, Remove, and Rearrange Columns

To add, remove, or rearrange columns, use one of the following:

The table personalization dialog: It offers some simple settings for column layout. Use this if you have only a few columns to choose from and/or you use the view settings dialog.
The p13n dialog: Besides various complex view settings, it also provides settings for column layout. Use this if you have a large number of columns to choose from and/or you use this dialog anyway for view settings.

In both cases, trigger the dialog via the settings button in the table toolbar. As short cut, use Ctrl+comma.

You can also use drag and drop to rearrange columns (sap.ui.table.Table, property: enableColumnReordering). If you allow rearranging via drag and drop as well as via a dialog, keep both places in sync.

Resize Columns

Resizing columns works differently on touch and non-touch devices.

Non-touch devices: Drag and drop the column separator on the right side of the column. Double-clicking the column separator optimizes the width of the column to the data currently loaded into the front end, which is usually about 100 rows.
Touch devices: Clicking the column header reveals two buttons: one for opening the column header menu, another one for resizing the column. Drag and drop this second button to resize the column.

Freeze Columns

To freeze columns, offer the setting in the column header menu (sap.ui.table.Table, property: enableColumnFreeze). Selecing Freeze on a column freezes all columns from the first one to the one where Freeze is selected. On this column, the menu entry changes from Freeze to Unfreeze.

Frozen column

Highlight Items

To show that an item needs attention, a highlight indicator can be shown in front of the item. The highlight indicator can be used to indicate:

A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.ui.table.Table, aggregation: rowSettingsTemplate)

Highlighted items

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.

'Export to Spreadsheet' menu button

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.

Note

If a user has selected multiple cells to overwrite, but the focus is placed outside of the selection, pasting will follow the guidelines for inline creation as above. This can happen, for example, when the user uses the arrow keys on the keyboard to move the focus.

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

The following additional properties are available for the grid table:

The property: width defines the width of the grid table.
The property: rowHeight defines the height of each row in the grid table. Since the height required is calculated automatically by the grid table, this property is only needed rarely.
The property: columnHeaderHeight defines the height of the column headers. Since the height required is calculated automatically by the grid table, this property is only needed rarely.
The property: columnHeaderVisible can be used to hide the column headers. Always show the column headers.
The property: showColumnVisibilityMenu provides an additional entry in the column header menu that allows columns to be shown or hidden. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
The property: visibleRowCount defines the height of the grid table. Show as many rows as fit on the screen.
The property: visibleRowCountMode defines whether the height of the grid table is fixed or automatically calculated based on the space provided by the underlying container. For automatic calculation, make sure that all rows have the same height.
The property: minAutoRowCount defines the minimum number of rows that must be shown if the property: visibleRowCountMode is set to “auto”. Show at least three to five rows.
The property: firstVisibleRow defines the first row shown in the visible area of the grid table. The grid table is scrolled accordingly.
The property: allowColumnReordering is deprecated. Do not use it. Use the property: enableColumnReordering instead.
The property: editable does not have a visible effect. Do not use it.
The property: enableCustomFilter changes the filter entry in the column header menu from an edit box to Filter…. Selecting this entry throws an event to which apps can react, for example, by opening a dialog. In general, you should choose the built-in filter over your own implementation. Specifically, keep filtering via the column header menu simple, while offering more advanced options via the table personalization dialog.
The property: enableBusyIndicator has not yet been fully implemented. Do not use it.
The property: title adds a line of text on top of the grid table. Do not use this. To add a title to the table, use a toolbar.
The property: footer adds a short text at the bottom of the table.
The property: Busy sets the grid table to busy state. While in busy state, the whole table cannot be used and items cannot be read due to an overlay.
The property: Tooltip does not have an effect. Do not use it.
The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). Do not use it.

sap.ui.table.Column

The following additional properties are available for the column:

The property: visible defines whether a column is shown or hidden.
The property: name defines the name shown in the column header menu for showing and hiding columns. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
The property: headerSpan defines whether one column header is used for one or several columns. To prevent adverse side effects, always use one column header for only one single column. Do not use this property.
The property: Tooltip does not have an effect. Do not use it.

sap.ui.table.Column

The following additional properties are available for the column:

The property: visible defines whether a column is shown or hidden.
The property: name defines the name shown in the column header menu for showing and hiding columns. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
The property: headerSpan defines whether one column header is used for one or several columns. To prevent adverse side effects, always use one column header for only one single column. Do not use this property.
The property: Tooltip does not have an effect. Do not use it.

Resources

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

Elements and Controls

Analytical Table (guidelines)
Bullet Micro Chart (guidelines)
Comparison Micro Chart (guidelines)
Feed List Item (guidelines)
Link (guidelines)
List Report Floorplan (guidelines)
Multi-Input Field (guidelines)
Responsive Table (guidelines)
Stacked Bar Micro Chart
Table Personalization Dialog (guidelines)
Table Toolbar (guidelines)
Tree Table (guidelines)
Variant Management (guidelines)
View Settings Dialog (guidelines)

Implementation

Column (SAPUI5 API reference)
Column Menu (SAPUI5 API reference)
Grid Table (SAPUI5 API reference)
Grid Table (SAPUI5 samples)

Chart Color Palettes

SAP Fiori uses qualitative, sequential, and semantic color palettes for chart visualization.

This article explains what the three color palettes are designed to do and how you can leverage their unique properties.

Palette Overview

For color names and HEX values, see Chart Color Palettes – Values and Names.

Qualitative Color Palette

Designed to provide visual differentiation between data points using a specific order of colors.

Qualitative colors

Sequential Color Palette

There are 12 colors with 9 tints and shades for each, which are designed to visualize high to low values.

Guidelines

It is not recommended to use more than six sequential tints and shades for different measures.

Sequential chart colors

Semantic Color Palette

Designed to communicate good (positive), bad (negative), critical and neutral values. The naming of the semantic values is generic and application teams determine the contextual usage of semantics within the charts.

Semantic colors

Rules

Only use colors contained in the SAP chart palettes.
To ensure that we maintain visual design consistency across all charts used in all SAP applications, you should only use colors from the SAP color palettes.
Only use one palette per chart.
Don’t combine colors from different palettes in the same chart. Each palette has been carefully designed to serve a distinct purpose.
Ensure chart color token names are referenced in the code – not HEX values!
To support consistent color implementation across SAP UI technologies, as well as our theming capabilities, colors are defined by token names. This means that the HEX values of the colors may not be exactly the same in past, present, and future SAP visual design themes. This flexibility is made possible by the fact that the color token names will stay the same across all past, present and future SAP themes. You can get the color names and corresponding HEX values from the article on color palette values and names.
Don’t use color to distinguish between forecast, actual, and target values.
Use semantic patterns instead.

Default Colors

By default, every chart type comes with built-in colors that are applied automatically, based on your dataset. Here are three examples:

1. When only one series is displayed, the first color from the qualitative palette is automatically applied to each item.

Column chart: One series

2. When multiple series are displayed, more colors from the qualitative palette are automatically applied to each item in the predetermined sequence.

Column chart: Three series

3. Colors from the sequential palette are automatically applied to the heatmap.

Default colors in a heatmap

Changing the Colors

There are three ways to change the colors in charts:

By Category Item

In the example below, one category has been highlighted using the second color from the qualitative palette.

Column chart with a highlighted category

By Series

In the example below, the series use different shade of the same color because one series must be more visible than the other.

Column chart: Two series

Based on Value

In the semantic color example below, the data points are red if their value is below a certain threshold, green if their value is above another threshold, and orange if their value is between the two.

Column chart with encoded values

Developer Hint

You can customize chart colors using the property: plotArea.dataPointStyle.
When you customize the colors, you must define colors for all your data points.
If no color has been assigned to a particular data point, the chart component automatically assigns the color black to indicate that no color has been assigned.
If for some reason multiple colors are assigned to the same data point, the last assigned color is applied.
You must manually define the labels that are associated with the colors in the legend. The chart components can’t do this automatically.

Qualitative Palette

The colors in the qualitative palette don’t carry semantic meaning. The palette has been designed to provide visual differentiation between data points by virtue of the fact that each color is visually distinct.

Guidelines

We recommend using the colors in the sequence illustrated, as opposed to using any colors simply because you prefer them.
It is not recommended to overload charts with additional colors. Nevertheless, for edge cases, you can apply darker shades of the same colors using the sequence palette, as shown in this example.

Qualitative palette

Qualitative palette - additional colors

For color names and HEX values, see Chart Color Palettes – Values and Names. Darker shades shown are taken from the sequence palette. Example: sapChart_Sequence_1_Minus2, sapChart_Sequence_2_Minus2, sapChart_Sequence_3_Minus2, etc.

Highlight Category Items

By default, all the categories use the first color from the qualitative palette. However, you can use other colors from the qualitative palette if you want to highlight category items.

Using the qualitative palette to focus on a category item

Group Items by Color

You can use the qualitative palette to group items into categories. In this example, we use green for Europe, blue for America, and orange for Asia.

Using the qualitative palette to show a hierarchy

Semantic Palette

The semantic palette is designed to communicate bad (negative), critical, good (positive), and neutral values.

To maximize flexibility for chart design application teams, the semantic palette contains a selection of 9 tints and shades in each of the 4 main semantic colors.

Guidelines

We recommend reducing the number of colors to five or six shades to visualize each semantic level.

Semantic palette

For the full set of color options, including color names and HEX values, see Chart Color Palettes – Values and Names.

Using the Semantic Palette

Here are some ways you can use the semantic palette:

Illustrate the Top Three Values

This column chart uses the semantic palette to display the sales revenue per month. The color green is used to highlight the top three months with the highest revenue.

Column chart: Top three values

Show Positive and Negative Series

These stacked bars represent the availability of materials. The available series is green, the inspection series is orange, and the blocked series is red.

Stacked bars: Good and bad values

Denote Good or Bad Values

Each data point has a color based on its value. Data points are red if their value is below a certain threshold, green if their value is above another threshold, and orange if their value is between the two.

Column chart: Good and bad values

Visualize Different Levels

In this geomap, green is used to indicate states with good performance, and red for states with bad performance. The different shades express different levels of good and bad performance.

Geomap: Levels of performance

Default Color Shade Names

The default color shade names in the semantic palette are:

sapChart_Sequence_Bad
sapChart_Sequence_Critical
sapChart_Sequence_Good
sapChart_Sequence_Neutral

Column chart: Level 1 of the semantic palette

Selecting the Correct Combination of Shades (Semantic Palette)

There are 4 semantic colors with 9 tints and shades for each that are used to maximize flexibility for chart design application teams. For the full set of color options, see Chart Color Palettes – Values and Names.

The table below gives an example of how to combine shades for bad (negative) values. You can apply the same principle to critical, neutral, and good (positive) values.

No. of Levels

Shades to Use

Color Token Names

1 level

sapChart_Sequence_Bad

2 levels

sapChart_Sequence_Bad_Plus2
sapChart_Sequence_Bad

3 levels

sapChart_Sequence_Bad_Plus2
sapChart_Sequence_Bad
sapChart_Sequence_Bad_Minus2

4 levels

sapChart_Sequence_Bad_Plus2
sapChart_Sequence_Bad_Plus1
sapChart_Sequence_Bad
sapChart_Sequence_Bad_Minus1

5 levels

sapChart_Sequence_Bad_Plus2
sapChart_Sequence_Bad_Plus1
sapChart_Sequence_Bad
sapChart_Sequence_Bad_Minus1
sapChart_Sequence_Bad_Minus2

6 levels

sapChart_Sequence_Bad_Plus3
sapChart_Sequence_Bad_Plus2
sapChart_Sequence_Bad_Plus1
sapChart_Sequence_Bad
sapChart_Sequence_Bad_Minus1
sapChart_Sequence_Bad_Minus2

Guidelines

We recommend reducing the number of colors to five or six shades to visualize each semantic level.
It’s important to select the correct combination of shades according to the number of levels you want to express, as in the best-practice example above.

Sequential Palette

The sequential color palette is designed to visualize high to low values for different measures.

Generally speaking, the lighter the shade, the lower the value. The darker the shade, the higher the value.

Sequential palette

For color names and HEX values, see Chart Color Palettes – Values and Names.

Using the Sequential Palette

Here are some ways you can use the sequential palette:

Distinguish between Past and Present

These two series use different shades of the same color to distinguish between last year and the current year.

Column chart: Two series

Show Time Gradation

These stacked bars represent payable aging by country. The different gradations of brightness are used to represent different time periods.

Stacked bars: Time gradation

Visualize Different Levels

This bullet chart shows direct costs in a dark shade and indirect costs in a light shade.

Bullet chart: Different levels

This geomap contains two measures. Shades of blue are used to visualize high and low values for one measure while shades of orange are used to visualize high and low values for the other measure.

Geomap: Multiple levels in two groups

Ranked Values

In this bubble chart, the size of the bubbles represents future sales deals. The probability of converting these deals is expressed using different shades of blue.

Bubble chart: Ranked values

Selecting the Correct Combination of Shades (Sequential Palette)

There are 12 colors with 9 tints and shades for each that are used to maximize flexibility for chart design application teams.

The table below gives an example of how to combine shades for the default category item color (sapChart_Sequence_1). You can apply the same principle to the other colors in the palette.

No. of Values

Shades to Use

Color Token Names

1 level

sapChart_Sequence_1

2 levels

sapChart_Sequence_1_Plus2
sapChart_Sequence_1

3 levels

sapChart_Sequence_1_Plus2
sapChart_Sequence_1
sapChart_Sequence_1_Minus2

4 levels

sapChart_Sequence_1_Plus2
sapChart_Sequence_1_Plus1
sapChart_Sequence_1
sapChart_Sequence_1_Minus1

5 levels

sapChart_Sequence_1_Plus2
sapChart_Sequence_1_Plus1
sapChart_Sequence_1
sapChart_Sequence_1_Minus1
sapChart_Sequence_1_Minus2

6 levels

sapChart_Sequence_1_Plus3
sapChart_Sequence_1_Plus2
sapChart_Sequence_1_Plus1
sapChart_Sequence_1
sapChart_Sequence_1_Minus1
sapChart_Sequence_1_Minus2

Guidelines

We recommend reducing the number of colors to five or six shades to visualize each semantic level.
It’s important to select the correct combination of shades according to the number of levels you want to express, as in the best-practice example above.

Resources

Elements and Controls

Chart (guidelines)
Chart – Color Palette – Values and Names (guidelines)
Design-Tokens (guidelines)
Theming (guidelines)

Implementation

SAP Theming Base Content
Chart tokens and technology-specific variables are provided as part of the GitHub repository of SAP themes.

Upload Set

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

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

When to Use

Use the upload set control if:

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

Do not use the upload set control if:

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

Components

Toolbar with upload and download controls
Edit and delete actions
Technical status
Attributes and statuses

Toolbar

The toolbar (1) can contain manual upload and download controls. The user can download one or several items selected in the list.

Developer Hint

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

Upload set anatomy

List

Actions (2)

By default, each item has an Edit button and a Delete button . Edit turns the title into an editable field so the item can be renamed.

Technical statuses (3)

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

Attributes and statuses (4)

You can display additional attributes and statuses below the file name. Attributes or statuses can include the name of the person who uploaded the file, the upload date, the version number, file size, and the object state in a workflow (such as “Approved” or “Overdue”).

Statuses can be shown in different colors, based on the visual guideline for semantic colors.

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

Information

Unlike the attribute, the object status differentiates its label and value with a different color, improving readability. You can use the object status to display any type of information.

Behavior and Interaction

Uploading Files

The upload set offers two basic working modes:

Instant upload (default): Files are uploaded as soon as they the user drops them onto the control or clicks the OK button in the file selection dialog.
Manual upload: All added files are first collected in the front-end list, where the user needs to trigger the upload.

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

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

Developer Hint

Using the Boolean property instantUpload, you can determine whether files are uploaded immediately or whether the user needs to trigger the upload explicitly.
The Boolean property uploadEnabled controls whether or not users are able to upload files.
For an example of a custom uploader, see the SAPUI5 sample.

Empty State

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

Interaction - No items

Drag and Drop

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

As the user hovers over the drop zone, a border appears around the upload set to indicate that the file can be released.

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

Interaction - Drag and drop

Opening Files

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

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

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

Renaming Files

The Edit function works identically on desktop and mobile devices.

The user clicks the Edit button .
The file name becomes an input field in which the existing name is highlighted. The icon buttons for Edit and Delete are replaced by two text buttons: Rename and Cancel.
When the user starts typing, the highlighted text is overwritten. Alternatively, the user can use the mouse or keyboard to change the selected text.
The new file name can be validated in two ways:
- The user clicks Rename.
- The user presses Enter.

Interaction - Renaming a file

Deleting Files

The Delete function works identically on desktop and mobile devices.

After clicking the Delete button for a file, the user is prompted to confirm the deletion.

Delete confirms the deletion and the file is removed from the list. Cancel aborts the process, closes the dialog, and brings the user back to the file list without making any changes. For more information on the pattern, see Message Box – Confirmation for “Delete”.

Clickable Attributes

Object attributes can be made clickable. This can be very helpful to provide users with a direct way to access certain information, such as a person’s profile and contact data, or the version history of a file.

Examples:

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

Guidelines

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

Responsiveness

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

Size S

Size M

Size L

Example

You can use the upload set control whenever users need to be able to upload multiple files. The example below shows the object page of a product, in this case a machine, with an Attachments tab containing several documents relating to the material specification and requirements.

Upload set in object page

Other possible scenarios:

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

Top Tips

When to Show, Disable, and Hide Actions

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

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

Do

Vertically align all actions

Don't

Don't position buttons differently. Place identical actions directly underneath one another.

Do

If an action is unavailable, disable it (for example, if a file was uploaded by another user).

Don't

Don't disable all actions. If users aren't allowed to use a certain action, don't show the corresponding button.

Do

If users aren't allowed to use a certain function, hide the corresponding button.

Usage

Use the carousel if:

You have strong visual representations of the items you want to display.
You want to display items sequentially or side by side.

Do not use the carousel if:

The items you want to display are uniform.

Responsiveness

The size of the control’s content area is adjusted automatically, depending on the amount of space available.

On non-touch devices, the user can navigate with the paging buttons displayed on the left and right of the control.

On touch devices, users can navigate through the pages by swiping or by tapping the arrow buttons, which are always visible. The tap interaction is required as an alternative to swiping to comply with accessibility standards.

The paging indicator (when activated) shows on all form factors. The paging indicator wraps if it is too long to fit onto one line.

Carousel - Size S

Carousel - Size M

Carousel - Size L

Layout

The main component of the carousel control is the content area in which the different items are displayed.

The (optional) paging indicator can float above or below the content area.

On non-touch devices, paging buttons either float above the left and right sides of the content area, or appear in the paging indicator area. This is controlled by the arrowsPlacement property.

Displaying multiple items

The layout of the carousel does not change when multiple items are displayed in the content area.

Behavior and Interaction

The content area contains either the current item or a set of items.

Navigation for Single Items

When the user navigates from the current item to another item, the current item is moved out of the content area, and the next or previous item slides in (depending on the direction of navigation).

On touch devices, users navigate with swipe gestures (swipe right or swipe left).

On non-touch devices, users navigate with paging buttons.

If the item set contains only one item, navigation is deactivated.

Paging button – Previous page

Paging button – Next page (hover)

Navigation for Multiple Items

When the user clicks one of the paging buttons, the rightmost or leftmost item is moved out of the content area, and the next or previous item slides in (depending on the navigation direction).

In addition, you can set the navigation to move through multiple items or an entire row with a single click on the paging button.

Carousel with multiple items

Looping

The carousel can be set to loop (property: loop). In this case, the carousel jumps back to the first item once all items have been displayed. If looping is not enabled, there is no forward navigation on the last item.

Paging

The current position inside the set of items is displayed using an optional paging indicator (properties: showPageIndicator, pageIndicatorPlacement).

Paging indicator - Icons

If there are more than 8 pages, the paging indicator changes from icons to numbers.

Paging indicator - Count

Resources

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

Elements and Controls

Image (guidelines)

Implementation

Carousel (sample in SAPUI5 Demo Kit)
Carousel (SAPUI5 API reference)

Carousel

The carousel allows the user to browse through a set of items. It can display one or several items at a time. From the displayed item or items, the user can navigate to either the next or the previous item.

Optionally, a paging indicator displays the user’s current position inside the set of items.

The carousel control is best used for browsing through a set of images. Viewing images one by one helps users to distinguish between different items. In a comparison scenario, it can also be useful to display several items side by side. The carousel is not limited to displaying images; it can contain any sap.m control.

Usage

Use the carousel if:

You have strong visual representations of the items you want to display.
You want to display items sequentially or side by side.

Do not use the carousel if:

The items you want to display are uniform.

Responsiveness

The size of the control’s content area is adjusted automatically, depending on the amount of space available.

On non-touch devices, the user can navigate with the paging buttons displayed on the left and right of the control.

On touch devices, the carousel control makes use of the swipe gesture to navigate through the items. As a result, the paging buttons are not displayed on touch devices.

The paging indicator (when activated) shows on all form factors. The paging indicator wraps if it is too long to fit onto one line.

Carousel - Size S

Carousel - Size M

Carousel - Size L

Layout

The main component of the carousel control is the content area in which the different items are displayed.

The (optional) paging indicator can float above or below the content area.

On non-touch devices, paging buttons either float above the left and right sides of the content area, or appear in the paging indicator area. This is controlled by the arrowsPlacement property.

Displaying multiple items

The layout of the carousel does not change when multiple items are displayed in the content area.

Behavior and Interaction

The content area contains either the current item or a set of items.

Navigation for Single Items

When the user navigates from the current item to another item, the current item is moved out of the content area, and the next or previous item slides in (depending on the direction of navigation).

On touch devices, users navigate with swipe gestures (swipe right or swipe left).

On non-touch devices, users navigate with paging buttons.

If the item set contains only one item, navigation is deactivated.

Paging button – Previous page

Paging button – Next page (hover)

Navigation for Multiple Items

When the user clicks one of the paging buttons, the rightmost or leftmost item is moved out of the content area, and the next or previous item slides in (depending on the navigation direction).

Carousel with multiple items

Looping

The carousel can be set to loop (property: loop). In this case, the carousel jumps back to the first item once all items have been displayed. If looping is not enabled, there is no forward navigation on the last item.

Paging

The current position inside the set of items is displayed using an optional paging indicator (properties: showPageIndicator, pageIndicatorPlacement).

Paging indicator - Icons

If there are more than 8 pages, the paging indicator changes from icons to numbers.

Paging indicator - Count

Resources

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

Elements and Controls

Image (guidelines)

Implementation

Carousel (sample in SAPUI5 Demo Kit)
Carousel (SAPUI5 API reference)

How To Use Semantic Colors / Industry-Specific Colors

You can use semantic colors and industry-specific colors to visualize the status or state of business data:

Semantic colors denote standard value states (such as positive, critical, or negative). Each state has the same basic meaning in all contexts.
Industry-specific colors reflect the color conventions in a line of business or industry. The meaning of each color depends on the business context.
In SAPUI5, industry-specific colors are called indication colors.

Nearly all input controls support semantic colors for value states, while industry-specific colors are only supported by a few UI elements.

For information about the color values for other themes, see Belize Colors and Quartz Light Colors.

Object status with semantic colors for value states

Object status with industry colors

When to Use

Do

Don't

Use semantic colors for value states if:

You want to highlight an important status.
You want to validate fields using form field validation.
Your app needs message handling.
You want to use the value states for a control.

Don’t use semantic colors if:

The color has no meaning and is used only for decoration.
You want to use colors in an industry-specific context, where the meaning of the colors differs from the standard semantic meaning. Use the industry-specific colors instead.

Use industry-specific colors if:

You want to use a color based on industry conventions (for example, when the meaning of a color is defined in an industry standard).

Don’t use industry-specific colors if:

The color has no meaning and is used only for decoration.
No special industry color conventions apply. Use the standard semantic colors for value states instead.

Overview

Semantic Colors for Value States

SAP Fiori has five semantic colors that are associated with the following predefined value states:

None
Positive
Critical
Negative
Information

Semantic colors for value states in a checkbox

Industry-Specific Colors

SAP Fiori has 10 generic indication colors that are intended only for industry-specific use cases. You can associate these colors with a specific meaning in a given industry context (for example, to reflect industry standards).

Each application must clearly communicate the meaning of each color. In addition to using a color, you must also provide a text, such as an object status. All colors require a corresponding descriptive text for accessibility purposes.

The indication color palette is supported exclusively by tables and the object status.

Object status with five industry-specific colors

Object status with three industry-specific colors

Using Semantic Colors for Value States

Only use a semantic color if you need to convey the meaning defined for the respective value state. This section looks at each value state in turn, and offers guidance on when to use each one.

None

This is the default state of an element. It means that no semantic or industry-specific meaning is assigned to it.

Use the “None” state if:

You want to use the default of a UI element.
There is no reason to use another value state.
You want to indicate a neutral object status.
A message contains non-critical, additional information for users.

Radio button, step input, and input in the 'None' state

Positive

This state stands for a good, positive situation, or for the successful completion of a task.

Use the “Positive” state if:

You want to highlight a good or positive status.
A message contains information about a process that was finalized without any issues. Users need this information later on (for example, to copy values to another app).

To indicate a successfully completed process, a short notification is enough. In this case, use a message toast and not the semantic color for the positive value state.

Radio button, step input, and input in a 'Positive' state

Critical

This state indicates a critical situation or warning.

Use the “Critical” state if:

You want to highlight a critical status.
A minor problem has occurred. The user can carry on working, but might run into an error later on.
The current mode or page can be finalized, but doing so might lead to an error later on.
The user input was validated and a minor problem occurred. The user can continue without fixing the problem, but might run into an error later on.
A message contains information about a warning.

Radio button, step input, and input in a 'Critical' state

Negative

Use this state for errors, or to indicate a bad or negative status or consequence.

Use the “Negative” state if:

Something bad has happened, or is about to happen. The issue requires the user’s attention. Until the issue is resolved, the user can’t carry on working.
You want to indicate that a value has caused an error.
The user needs to be prevented from finalizing the current mode or page.
The user input failed a validation, and the problem must be fixed before the user can continue.
A message contains information about an error.

Radio button, step input, and input in a 'Negative' state

Information

Use this state to highlight a piece of information.

Use the “Information” state if:

You want to draw attention to a control for an important purpose, such as visualizing the recommendations from intelligent systems in input fields.
You want to highlight newly added items, such as a new table row.

Don’t apply the semantic color for the information state to text. The blue text color is explicitly reserved for links. If you need to emphasize text, use bold or italic formatting instead.

Radio button, step input, and input in an 'Information' state

Using Industry-Specific Colors

There is no predefined meaning for the individual colors in the generic palette. If you want to use one or several colors from the industry-specific color palette in your application, proceed as follows:

Define the meaning for each color you want to use.
Whenever you use an color, provide an additional text indicator (such as an object status) to ensure that the text is clear and accessible.
Once you have defined the meaning for a color, use the color/meaning consistently within your application.

Color Overlap

By default, some colors are the same in the semantic palette and the industry-specific color palette (such as red, orange, green, and blue). This is intended. However, the two color palettes can be themed independently, which means that end users might not see the same colors in both.

No Palette Mix

Some UI elements support both the semantic color palette and the industry-specific color palette. However, you can only use one color palette at a time. It is not possible to mix different colors from both palettes.

Color Hierarchy

If an UI element would have multiple semantic or industry-specific color statuses at the same time, the control may need to determine an “overall color” at first.
In this case, the overall color is based on the color hierarchy: colors higher up in the hierarchy take precedence over those lower down. Note that there is only one hierarchy for both semantic colors and industry-specific colors.

Color hierarchy

Styles

The semantic colors and industry-specific colors are themeable.

Resources

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

Elements and Controls

Quartz Light Colors (guidelines)
Belize Colors (guidelines)
UI Element States (guidelines)
Form Field Validation (guidelines)
Message Handling (guidelines)
Object Display Components (guidelines)

Implementation

Object Status (SAPUI5 samples)
Input with Different Value States (SAPUI5 samples)

Tree Table

A tree table contains a hierarchical set of data structured in rows and columns and grouped into nodes. The analytical table (also know as ALV) can provide additional details in several non-hierarchical columns per line item.

Usage

Trees are used to display and work with large amounts of hierarchical data. They have a high data density and therefore convey an immediate feeling of complexity. Ideally, you should only show trees with a lot of hierarchical data as a last resort. Try the following instead:

Break down the data into manageable chunks and allow the user to navigate or drill down between them.
Use charts with drilldown functionality until the amount of data is more manageable.

Responsiveness

A tree table is available for desktops and tablets, but not in smartphone sizes. It supports touch 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.

Tree table shown on a desktop

Tree table shown on a tablet

Types

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

For a desktop, you can also display even more rows on the same screen height by adding the condensed mode in addition to the compact mode. This renders less white space for each item.

Note that the condensed content density has always to be set in addition to compact. Do not use condensed on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable and / or unwanted results, e.g. cozy sized controls in condensed sized containers, missing paddings, etc.

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

Furthermore, condensed mode is not available for Internet Explorer 9. If condensed mode is to be used, please provide a fallback.

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

Compact Mode

Tree table – Compact mode

Condensed Mode

Tree table – Condensed mode

Components

Column Header

The column header provides the label for the corresponding column and access to the column header menu.

Resizing columns works in the following ways:

Mouse interaction: Dragging the separator line between two columns (sap.ui.table. Column, property: Resizable). Double-clicking optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable).
Touch interaction: The user taps the column header to reveal two buttons: one for showing the column header menu and one for resizing. Drag the latter to resize the column.
Keyboard interaction: The width of the focused column header can be increased with Shift+Right and decreased with Shift+Left.

After resizing a column, the adaptation of the column widths depends on how the column width is set:

If column widths are set in pixel-based units (px, em, rem), the corresponding column is adapted and following columns are moved accordingly. The width of all other columns is not affected.
If all the columns together take up less width than the table control, an empty space is added. If all the columns together take up more width than the table control, a scrollbar appears.
If all column widths are set in percentage or “auto”, resizing one column might also lead to the automatic resizing of some or all other columns. The position of the resized column might also be affected. This is done to ensure that the whole table width is used and no white space is added. A scrollbar appears only, if all or most of the columns get very small. To avoid the unintended side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

Columns can be rearranged by dragging the column header to another position (sap.ui.table.TreeTable, property: enableColumnReordering). Keyboard: the focused column header can be moved by one position to the corresponding direction with Shift+Left / Shift+Right.

Tree table – Column header

Opening the column header menu on touch devices

Fewer columns than space available

Line Item

A line item contains a set of cells and provides options for selecting the item.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.TreeTable, property: rowHeight).

Tree table – Line item

In rare cases, show the actions within the line item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. Provide a separate column per action. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

Tree Column

The first colum (tree column) provides the hierarchical structure.

Tree table – Tree column

Expand/Collapse Button

The expand/collapse button is offered on container nodes to allow the child items of the corresponding container to be shown or hidden.

Tree table – Collapse

Tree table – Expand

Container Node

A container node is a line item that contains child elements.

Tree table – Container node

Leaf Node

A leaf node is a line item that does not contain child elements.

Tree table – Leaf node

Cell

Each cell provides one data point. It can contain one of the following controls to display the data point:

Text
Label
Object status
Icon
Button
Input field
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).

Tree table – Cell

Tree Cell

A tree cell is a cell inside the tree column. Besides its data point, it provides a collapse/expand button on container nodes, and it indents the different hierarchy levels.

Tree table – Tree cell

Column Header Menu

For the tree column, the column header menu can contain the menu item Freeze and a Filter field, in which the user enters free text.
For all other columns, only the free text filter is available.

Tree table – Tree column header menu

Selection Cells

For multiselection tree tables, the first column contains checkboxes for selecting line items. Besides multiselection, the tree table offers a single-selection mode and also a read-only mode, in which line items are not selectable.

Tree table – Selection cells

Select All

For multiselection tree tables, the column header can contain a checkbox above the selection cells for selecting or deselecting all line items.

Tree table – Select all

Scrollbar

The tree table allows horizontal and vertical scrolling. You can add any number of line items to the tree table, which uses “lazy loading”.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.TreeTable, property: rowHeight).

The tree table is optimized to allow faster scrolling within the first 1000 items.

Tree table – Vertical scrollbar

Behavior and Interaction

Selection

The tree provides the following possibilities:

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

Tree table – No selection

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

Tree table – Single selection

Multiple selection: One or more items can be selected. The tree table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back. The Shift key can be used to select a range.

For multiple selection, you can choose between two variants.

Multi-toggle mode (property: selectionMode = MultiToggle)
Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)

These variants behave differently when the user selects more items than are currently loaded in the front end.

Multi-toggle

In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end (keyboard: Ctrl+A). All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

Multi-selection plug-in

If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:

By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
- The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and a message can appear (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
- If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets (Keyboard: Ctrl+A).
If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.

Information

When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.TreeTable, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

Tree table – Multiple selection

Multi-selection plug-in with a limit

Selection Behavior

An item can be selected in different ways, depending on the configuration of the tree table (sap.ui.table.Table, property: selectionBehavior):

Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection tree tables if clicking a row or a cell is not used for anything else.
RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection tree tables if clicking a row or a cell is not used for another purpose, such as navigation.

Set the property collapseRecursive to “false” in order to keep the selection on subnodes even after collapsing and expanding the root node.

Drag and Drop

One or several items can be repositioned within a table or moved to other UI elements using drag and drop operations (sap.ui.table.TreeTable, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop

Column Header Menu

Sort

The column header menu can provide two sort options (sap.ui.table.Column, properties: sortProperty, showSortMenuEntry):

Sort Ascending
Sort Descending

The user selects one of these options to sort the corresponding column accordingly (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

Sort settings in column header menu

Filter

The column header menu can provide a search field for entering free text. If the user enters a term in the input field and triggers the search by pressing Enter, the tree is filtered by the tree column and the corresponding value. If no items match the filter values, the filtered tree table may be empty.

Tree table – Filter

Freeze Columns

The Freeze/Unfreeze option is provided in the column header menu of all columns. Using Freeze on one column freezes all columns from the first one to the selected one.

Tree table – Freeze

Column Handling

Show/Hide Columns

Columns can be shown and hidden. If the tree column is hidden, the following column is the tree column.

Rearrange Columns

The user rearranges columns by dragging and dropping the corresponding column header. The tree column is always the first column and cannot be dragged. Keyboard: the focused column header can be moved by one position to the corresponding direction with Ctrl+Left / Ctrl+Right.

Resize Columns

Columns are resized as follows:

Mouse interaction: The user drags the separator line between two columns (sap.ui.table. Column, property: Resizable). Double-clicking the line optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable). Note that auto-resizing works only if the cells in this column contain one of the following controls: text, label, link, or input.
Touch interaction: The user clicks or taps the column header to reveal two buttons: One to show the column header menu, and one for resizing. The user drags the latter to resize the column.
Keyboard interaction: The width of the focused column header can be increased with Shift+Right and decreased with Shift+Left.

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows (like group headers). Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or Shift+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Tree table with context menu

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.

Developer Hint

The tree table itself has no influence on the filter result. It sends a filter request and displays whatever comes back. Make sure that the result set is meaningful.

Sorting

First of all: Is sorting meaningful in your tree? If so, decide on a meaningful default sort order.

If sorting is meaningful, is it meaningful on all levels? Or does the tree structure need to be stable? In the latter case, sort only leaves, but not nodes.

Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the tree column.

To display the current sort state, an icon is shown in the column header of the most recently sorted column. This icon indicates the sort direction (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

The descending sort order must always be the exact reverse of the ascending sort order. For each column, provide a meaningful sort order. For example:

Sort text alphabetically
Sort numbers by their value
Sort status information by the severity of the status:
- Ascending: Sort status information from positive to negative, with neutral last.
- Descending: Sort status information from negative to positive, with neutral first.

- Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
- Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Loading Data

To indicate that the table is currently loading items, use the busy state (sap.ui.table.TreeTable, property: busy). Do not show any items or text. As soon as the data has been loaded, remove the busy state and show all items.

Initital Display

Think of the initial expand / collapse state of a tree: If your structure contains many items on the root level, it might make sense to collapse the whole tree in the beginning.

In contrast, if the main items to work with are displayed on a deeper level (e.g. the parent nodes are just some kind of categorization), the tree should be expanded up to the first level where the needed items appear.

Errors and Warnings

To indicate that the tree table contains items with errors or warnings, show a message strip above the tree table. On the message strip, provide information on errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

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

Developer Hint

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

Selection

We strongly recommend using the multi-selection plug-in. This ensures that all items selected using Select All or as part of a range are included – even if some items were not initially loaded in the front end. This is not the case if you use the multi-toggle option.
Do not limit the range selection for the multi-selection plug-in unless you have to.
- If the dataset is small and/or completely available in the front-end, set the limit property to 0 to enable the Select All option and allow users to select any range.
- If you have a large dataset, set a limit on the number of selected items to avoid performance issues. Also bear in mind that some actions won’t be helpful if the dataset is too big (for example, a delete operation on 2 million database entries).
When setting a limit, also display the corresponding message when the user selects more items at once than the limit allows (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification).
For single-selection 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:

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.
Open a dialog for larger tree tables with up to 8 editable columns. Save the new item at dialog level.
Navigate to a new page. This behavior should only be used for very complex scenarios that cannot be handled by a dialog (for example, 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.

Do

Example of an acceptable use of tree tables

Do

A clear parent-child relationship

When you use trees, you should choose broad hierarchies over deep hierarchies. Deep hierarchies make finding items more complicated. So try to reduce hierarchical levels where possible, especially if the hierarchy is not natural. Ideally, a tree should have a maximum of four levels, the first two of which should contain the most important items.

Don't

Avoid unnecessary depth in the hierarchy

Do

Favor breadth over depth in the hierarchy

You can use the following methods to reduce hierarchy levels:

Avoid single root nodes. A single root node is often used to provide a Select All feature. Since the tree control provides an extra space for a Select All feature, the root node is not usually needed.
When you use only two levels, choose a grouped table or grouped ALV over a tree table control. Expand all groups for the default delivery.
Container nodes at the top level can usually be replaced by tabs or value pickers.
Eliminate unnecessary mid-level containers, for example, by combining redundant ones.
Exercise care when using a tree due to its overall complexity. The hierarchical structure of the data does not necessarily mean that a tree control is required.

Design Concepts

The tree table can be used to display large amounts of hierarchical data. Unfortunately, tree tables have a high data density and therefore convey an immediate feeling of complexity. Ideally, tree tables with large amounts of data should only be shown if there is no other option. You should instead try the following:

Flatten the data. A list, table, or ALV is still complex, but less so than a tree table.
Break down the data into manageable chunks. Allow the user to navigate or drill down between them.
Use charts with drilldown functionality until the amount of data is more manageable.

Try to avoid horizontal scrolling in the default delivery.

Navigation

To trigger navigation on line item level, choose one of the following options:

Use a link for the attribute that identifies the row. Clicking the link triggers the navigation. This is the preferred option.
Add the RowActions column and show the navigation arrow ( ) at the end of the row. No column header text is required. The navigation column is fixed and will not scroll away. Users also cannot personalize this column. The navigation arrow triggers the navigation.
Do not use the RowActions column for actions other than navigation and deletion.

Special case: Multi-selection in a 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

When you use trees:

Choose breadth over depth.
Emphasize important values. Do not let the user run into a wall of text without guidance. You can use bold text for this.
Try to minimize the number of columns, especially if there is a large number of rows.
Optimize column width for its initial visible content. Do not automatically adjust column width based on content changes.
Do not wrap content, truncate it. End users can easily change the column width to see the full text.

Don't

Avoid truncating the initial visible content in the default delivery

Don't

Never wrap texts

Maintain a fixed layout, except when the user wants to change it.
In the default layout, use the tree column for the item name or data that identifies the row. This helps the user to choose between different items.
Create a clear and immediately understandable hierarchy. Use clear parent-child relationships. If this is not possible, add a child in different nodes to help the user find the element.

Do

Acceptable: repeat entries to optimize finding items

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

Highlight Items

To show that an item needs attention, a highlight indicator can be shown in front of the item. The highlight indicator can be used to indicate:

A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.ui.table.TreeTable, aggregation: rowSettingsTemplate)

Highlighted items

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items. These are keyboard operable and available on all browsers.

Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within a tree table, use the following options:

For dropping items as a child, use whole nodes as drop targets (sap.ui.core.dnd.DropPosition.On).
For dropping items on the same level, use the space between items as drop targets (sap.ui.core.dnd.DropPosition.Between).
If you want to allow users to drop items as a child or sibling, offer both drop targets (sap.ui.core.dnd.DropPosition.OnOrBetween).

This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop target on an item

Do not combine rearranging items within one level and sorting. If you really need to do so, make sure there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

Moving items from one node to another can be combined with sorting without any issues.

Don't

Do not combine rearranging items on the same level with sorting

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.

'Export to Spreadsheet' menu button

Resources

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

Elements and Controls

Bullet Micro Chart (guidelines)
Button (guidelines)
Checkbox (guidelines)
Combo Box (guidelines)
Comparison Micro Chart (guidelines)
Date Picker (guidelines)
Filter Bar (guidelines)
Formatting (guidelines)
Icon (guidelines)
Icon Tab Bar (guidelines)
Input (guidelines)
Label (guidelines)
Link (guidelines)
Multi-Combo Box (guidelines)
Multi-Input Field (guidelines)
Select (guidelines)
Stacked Bar Micro Chart (guidelines)
Table (guidelines)
Text (guidelines)

Implementation

Tree Table (SAPUI5 API reference)

Smart Table

Intro

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

When to Use

Use the smart table if:

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

Do not use the smart table if:

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

Components

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

The components of a smart table

Table Toolbar

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

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

Title
Item counter
Variant management
Show Details / Hide Details
View Settings
Export to Spreadsheet
Maximize / Minimize

In addition, you can add app-specific actions.

Title

Displaying a title is optional (property: header).

Guidelines

Add a title whenever the title is not indicated in the surrounding area.
If you don’t display a title, ensure that you still provide a table title for screen reader users.

Developer Hint

If there is no title title, support screen reader users as follows: create a simple table in the XML view, use ariaLabelledBy to point to the corresponding text, and add this table to the smart table. Make sure that the table type within the smart table is set accordingly. The smart table will take care of the rest (creating columns, and so on).

Item Counter

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

Guidelines

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

You expect this to cause performance problems.
You use a responsive table and use the More button for loading additional items. Use the item counter on the More button instead.

Variant Management

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

Guidelines

Use variant management only if really needed.

Show Details / Hide Details

The Show Details / Hide Details button is mandatory with and only available for the responsive table. Columns with a low priority (low or medium priority on phones) are hidden in the pop-in area (properties: demandPopin, enableAutoColumnWidth, showDetailsButton, annotation: UI.Importance).

You can define which priority levels cause the columns to be hidden (property: detailsButtonSettings). The button only appears if there are columns that belong in the pop-in area. Columns disappear from right to left but columns with the priority “High”, are never hidden. They are shown in the pop-in area if they do not fit on the current screen size

Details hidden

Details shown

View Settings

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

Guidelines

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

Sort and Filter

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

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

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

Guidelines

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

Developer Hint

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

Group

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

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

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

Guidelines

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

Column Settings

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

Guidelines

If sorting, grouping, and/or filtering are needed, also show the column settings (sap.ui.comp.smarttable.SmartTable, property: useTablePersonalisation).

Developer Hint

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

Export to Spreadsheet

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

Guidelines

Only offer the Export to Spreadsheet option if your end users typically export the data shown in the table to work with it in a spreadsheet application.
- This is usually the case if data is collected from several systems and analyzed in the spreadsheet application.
- This is not usually the case for worklists, attachment lists, tables with only a few items, shopping carts, or data that does not need to be analyzed.
If you offer the Export to Spreadsheet button, use the front-end export.
If your table has columns with non-textual content, provide a textual equivalent for those columns. Non-textual content is not exported.

Warning

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

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

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

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

Maximize / Minimize

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

Guidelines

Use Maximize / Minimize only if really needed.
Do not use it in list reports, worklists, analytical list pages, and initial pages. We recommend it in object pages with multiple grid tables in one tab.
Do not use it for responsive tables with a More button.
Do not use it if the table is in a dialog or popover.

App-Specific Actions

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

Developer Hint

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality, such as a table title, item counter, variant management, view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).
If you are using a custom toolbar in a responsive table, show the bottom border of the toolbar. For all other tables, do not show it (property: style, value: clear).
The property placeToolbarInTable adds the toolbar to the corresponding aggregation of the inner SAPUI5 table. In most cases, set this to “true”, especially when you are using the custom toolbar with the responsive table. Otherwise, the table toolbar cannot stick to the top of the surrounding layout container.

Infobar

Infobar with filter information

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

Guidelines

For the responsive table, the info bar is mandatory.
For all other tables, do not show the info bar.

Table

Responsive table within a smart table

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

Table
Column Visibility
Column Layout
Column Headers
Column Content

Table

The table provides the following features:

You can use the responsive table, grid table, tree table, or analytical table within the smart table (property: tableType).

Guidelines

The analytical table, tree table and grid table are not fully responsive. They are available only for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
For the responsive table, the smart table initially loads 20 items and shows a More button for loading additional items. Change this behavior if:
- You expect fewer than 200 items. Load all items from the start (sap.m.Table, property: growing).
- You expect more than 200 items. Adapt the number of items initially loaded to cater for large screens, and load additional items automatically when the user scrolls down (sap.m.Table, property: growingScrolllToLoad).

Developer Hint

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

Developer Hint

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

While the grid table, analytical table, and tree table support multi-selection by default within the smart table, the responsive table does not offer any kind of selection. The selection mode can be changed.

Developer Hint

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

Column Visibility

Columns are created automatically. Items are rendered based on the properties and metadata of the underlying OData service (annotation: LineItem, properties: entitySet, tableBindingPath, initiallyVisibleFields, ignoreFields). A column is generated for each OData entity property.

Developer Hint

If a column needs to be in the model but should not be shown, you can hide it from both the table and the P13n dialog (property: ignoredFields, annotation: UI.Hidden).

Use this option if:

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

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

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

Developer Hint

Columns can be removed at runtime. This is useful if the same table is used for similar, but slightly different objects. For one of the objects, specific columns need to be shown, for others they must be hidden, and users must not be able to add them in the personalization settings (function: deactivateColumn).

You can define which columns are initially visible when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleFields).

Guidelines

Keep the number of initially visible columns to a minimum. Avoid pop-in behavior (responsive table) or horizontal scrolling (all other tables) on a tablet screen size in the default delivery (annotation: PresentationVariant/ LineItem).
Also keep the number of additional columns offered in the personalization settings to a minimum. You can use the P13n dialog to let users show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value: false).

For each column that is initially visible, the LineItem annotation includes a DataField record, which allows you to influence the content rendering of the smart table.
For columns that are initially invisible, the content rendering can also be influenced via the annotation DataFieldDefault.

Developer Hint

If the same column is defined via LineItem and via DataFieldDefault, LineItem wins.

Column Layout

A default column width can be calculated for each column based on the data type, the column label, the edit/read-only state, and the annotations: textArrangement, MaxLength for strings, Precision and Scale for numeric data (property: enableAutoColumnWidth).
The calculated width is between 3 rem and 20 rem. Apps can change this default width if needed (annotation: CSSDefaults).
If the combined width of all the columns is less than the width of the table, the remaining space stays empty.

Guidelines

Choose a column width that avoids truncation for the initial data and (if feasible) for the column header label. If the default column width doesn’t fit, change it.

Developer Hint

For the responsive table, enableAutoColumnWidth also applies the following changes:

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

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

Columns can be resized by dragging the column separator. If the combined width of all columns is less than the width of the table, the remaining space stays empty. The smart table provides column resizing automatically in the following cases:
- Grid table / tree table / analytical table: Column resizing is automatically enabled with the column settings.
- Responsive table: Column resizing is automatically enabled with the automatically calculated default column width.

Responsive table with automatically calculated column widths, resizing, and remaining space

If the automatically generated content does not fit for your use case, you can override the automatic behavior with your own column template.
You can also add further columns. This allows you to provide columns with app-specific or inline actions, columns which show calculated values (based on more than one OData entity property), or – for responsive tables – columns that show more than one control.

Developer Hint

To add or override columns (“custom columns”):

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

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

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

Column Headers

You can specify a column header text for each column (annotation: sap:label).
SAP S/4HANA Only:
Tooltips are available by default for smart table column headers.
In smart tables, texts that exceed the column width always truncate (see Column Layout). The tooltip allows users to read the full column header text without resizing.

Guidelines

Provide a column header text for each column. (annotation: sap:label).

The column headers contain the following settings:
- Sort Ascending, Sort Descending
- Filter: Opens the P13n Dialog. If this does not fit for your use case, exchange this menu item (property: enableCustomFilter)
- Group (only analytical table, only on dimension columns)
- Total (only analytical table, only on measure columns): This setting is not persisted (annotation: sap:aggregation-role, value: measure).
  If a column contains entries with different units of measurement, a Show Details link appears instead of the total. Clicking the link opens a popover showing the subtotals per unit of measurement.
- Freeze (only available for grid table, tree table, and analytical table): Must be added manually.

Guidelines

Offer column totals by default for all columns where totals make sense (annotation: PresentationVariant).

Developer Hint

To add a Freeze option manually, declare the corresponding table inside the smart table in the XML view, and use the corresponding settings for this inner table.

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

Column header menu for a dimension column of an analytical table within a smart table

Column header menu for a measure column of an analytical table within a smart table

Content

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

You can render the smart table in either read-only or edit mode (with no option to switch), or allow users to switch between the two modes (properties: editable, useSmartToggle).
In read-only or edit mode, the smart table renders the controls as listed in the table below, or uses the smart field for both modes. If you use smart fields together with the option to switch between read-only and edit mode, the smart table renders the read-only controls as in the list below, but uses the smart field for edit mode. The smart field limits the rendering options (aggregation: customData, key: useSmartField), but also allows for:
- Better control of the visibility of a field per row (smart field, annotation: FieldControl)
- Use of value help for input fields

Developer Hint

From a performance perspective, using the smart field is more expensive than using the controls provided by the smart table directly. With this in mind, follow the rules below:

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

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

	Read-only	Edit	Annotations / Edm type	Comment
Static text	Text	Input field	Edm.String
Decimal numbers	Text	Input field	Precision, Scale, Edm.Byte, Edm.Decimal, Edm.Double, Edm.Int16, Edm.Int32, Edm.Int64, Edm.SByte, Edm.Single
Status information	Object status or Icon	Input field	Criticality, CriticalityType, CriticalityRepresentationType	Do not use editable status information.
Key identifier	Object identifier (responsive table) Text (all other tables)	Input field for the ID	SemanticKey, Common.EditableFieldFor
Text and ID	Text, object status, or object identifier	Input field for the ID	TextArrangement	Use together with the annotation mentioned above for static text, status information, or key identifier. Sorting, filtering, and grouping only works for the ID, even if the ID is not displayed.
Links with/without quick view	Smart link	Smart link	SemanticObject	Smart links can be customized using the aggregation: `semanticObjectController`
Dates	Text	Date picker	Edm.DateTime, sap:display-format, value: date, IsCalendarDate
Dates and times	Text	Date/time picker	Edm.DateTime, Edm.DateTimeOffset
Times	Text	Time picker	Edm.Time
Fiscal periods	Text	Input field	IsFiscalYear, IsFiscalPeriod, IsFiscalYearPeriod, IsFiscalQuarter, IsFiscalYearQuarter, IsFiscalWeek, IsFiscalYearWeek, IsDayOfFiscalYear
Amounts with currencies	Two text controls	Input field for the amount	sap:semantics, value: currency-code	In edit mode, the currency is shown as static text next to the input field.
Phone numbers	Link	Input field	IsPhoneNumber	Opens the system application for making phone calls.
Email	Link	Input field	IsEmailAddress	Opens the system application for writing emails.
Pictures	Image	Input field	IsImageURL	Only available for the responsive table. In edit mode, the input field contains the URL to the image.
Boolean	Text	Checkbox	Edm.Boolean	For read-only, the displayed text is Yes or No.

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

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

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

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

Guidelines

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

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

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, export to spreadsheet, and P13n dialog (see the corresponding articles for details.) Note that the smart table provides limited options and not all settings of the underlying controls are available.

Empty Tables

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

If a table is initially empty:
No items available.
Overwrite this whenever a hint can be provided on how to fill the table with data.
(property: initialNoDataText, value: $NO_FILTERBAR)
If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
To start, set the relevant filters.
(property: initialNoDataText, value: $FILTERBAR)
If a table is used together with a filter bar and the filter does not return results, use the following text:
No data found. Try adjusting the filter settings.
(aggregation: noData, changeable at runtime)
If the user has hidden all of the columns in the personalization settings, the following text is shown:
Right now, there are no visible columns in the table. Please select the columns you need in the table settings.
This text cannot be changed.

Guidelines

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

An empty smart table

Errors and Warnings

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

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

Table containing warnings

Table containing errors and warnings

Guidelines

To show that an item contains an error,

Highlight the row accordingly.
Add the string (contains errors) and place it at the bottom of the column that identifies the line item (responsive table) or in the Editing Status column (all other tables).

Developer Hint

Binding-related messages are shown automatically.

Responsiveness

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

Toolbar Overview
Infobar
Responsive Table via auto pop-in mode
(sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true).
You can use the UI.Importance annotation to influence the priority of each column.
You can provide a Show Details button to let users show/hide columns with low importance (property: showDetailsButton).
Grid Table, Tree Table, Analytical Table are not fully responsive. They are available only for desktops and tablets. For smartphones, you need to take an adaptive approach by offering an additional UI.

Guidelines

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true). Ensure that the most important columns stay in the tabular layout as long as possible (annotation: UI.Importance). The most important columns are those that contain the following information:

The column that identifies the line item.
The column that contains the key attribute.

Developer Hint

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

Examples

Responsive table within a smart table

Grid table within a smart table

Top Tips

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

Properties

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

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

Usage

Use the analytical table (ALV) if:

The cell level and the spatial relationship between cells are more important than the line item. Examples include spreadsheet analyses and waterfall charts. Note that an analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
You have to work on more than 1,000 rows. In this case, the analytical table is easier to handle. In contrast to the responsive table, the architecture of the analytical table is optimized for handling large numbers of items. Note that an analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
Comparing items is a major use case. In this case, an analytical table might be more appropriate than a responsive table. In the analytical table, each cell contains only one data point. In contrast, the responsive table is more flexible regarding line items, including the ability to add more data points per cell and also the pop-in function. Both make comparisons more difficult. Note that an analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.

Do not use the analytical table (ALV) if:

You need a table. The responsive table is the default table in SAP Fiori. Additional use cases where you might need the responsive table include:

- You need to provide a total sum for one column. You can also add totals to the responsive table.
- The focus is on working on line items, not on cells. The responsive table is optimized for displaying complete items on all devices (such as purchase orders and purchase requisitions).
- Selecting one or more items is a main use case and details are needed to choose the correct item.
- Line items are independent of each other and no operation across columns is needed.
- You want to have only one implementation for all devices.

The main use case is choosing one item from a very small number of items with no additional details. A select or combo box might be more appropriate.
The main use case is choosing one out of several items with only a few details per item. A list might be more appropriate. Examples include the list in a list-detail scenario or an attachment list. Pay attention to the layout of the list item to ensure that it has a pleasant appearance.
You cannot provide an analytical binding on the technical side. In this case, a grid table will do the work. However, please note that the grid table doesn’t provide grouping, aggregation options, and is not responsive.
Data needs to be structured in a hierarchical manner. In this case, a tree table might be more appropriate. Although the analytical table can have several grouping levels, it is not as flexible when nodes at several levels contain children. Note that neither the tree table nor the analytical table are responsive. You will need to take an adaptive approach by offering an additional UI for smartphones and tablets.
You need an overview of a large amount of data. In this case, use charts.
You just need it for layout reasons. In this case, use a layout container like HBox or VBox.
You need read-only or editable field-value pairs. Use a form instead. The analytical table is not optimized for form-like input navigation.

Responsiveness

The analytical table is available for desktops and tablets, but not in smartphone sizes. It supports touch 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.

Analytical table (ALV) shown on a desktop

Analytical table (ALV) shown on a tablet

Components

An analytical table does not consist of other elements. However, it is common to use a toolbar above the analytical table.

The toolbar can contain entry points for the view settings dialog and the table personalization dialog or for the p13n dialog, as well as for view switches in the form of a segmented button, and buttons for Add, Edit, and other actions.

Behavior and Interaction

An analytical table is quite restricted in terms of its content, although it provides powerful features for working with the content.

Table Level

Scroll

An analytical table allows horizontal and vertical scrolling (sap.ui.table.AnalyticalTable, property: navigationMode, value: Scrollbar).

You can add any number of line items to the analytical table, which is known as “lazy loading”.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.AnalyticalTable, property: rowHeight).

The analytical table is optimized to allow faster scrolling within the first 1000 items.

Scroll bar

Select

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

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

Analytical table without item selection

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

Analytical table with single selection

Multiple selection: One or more items can be selected. The analytical table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back. The Shift key can be used to select a range. For multiple selection, you can choose between two variants.
- Multi-toggle mode (property: selectionMode = MultiToggle)
- Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)
These variants behave differently when the user selects more items than are currently loaded in the front end.

Multi-toggle

In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end (keyboard: Ctrl+A). All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

Multi-selection plug-in

If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:
- By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
- You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
  - The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and a message can appear (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
  - If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets. (Keyboard: Ctrl+A)
- If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.

Information

When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
The “minimum limit”: Internally, the analytcial table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.AnalyticalTable, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

Analytical table with multiple selection

Using the multi-selection plug-in with a limit

Selection Behavior

An item can be selected in different ways, depending on the configuration of the analytical table (sap.ui.table.Table, property: selectionBehavior):

Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection tables if clicking a row or a cell is not used for anything else.
RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection tables if clicking a row or a cell is not used for another purpose, such as navigation.

Compact, Cozy, and Condensed

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

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

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

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

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

Analytical table in compact mode

Analytical table in condensed mode - More items on the same screen real estate

Column Header

The column header provides the label for the corresponding column and access to the column header menu.

Columns are resized as follows:

Mouse interaction: The user drags the separator line between two columns (sap.ui.table.AnalyticalColumn, property: Resizable). Double-clicking the line optimizes the column according to the length of the data currently visible and the label of the column header (sap.ui.table.AnalyticalColumn, property: Autoresizable).
Touch interaction: The user clicks the column header to reveal two buttons: one to show the column header menu and one for resizing. The user drags the latter to resize the column.
Keyboard interaction: Users can increase the width of the focused column header with Shift+Right and decrease it with Shift+Left.

When the user resizes a column, the adaptation of the column width depends on how the column widths are set:

If column widths are set in pixel-based units (px, em, rem), the resized column is adapted and subsequent columns are moved accordingly. The width of all other columns is not affected.
If all the columns together do not use up the full width of the table control, empty space is added. If all the columns together exceed the width of the table control, a scrollbar appears.
If all column widths are set as percentages or “auto”, resizing one column automatically resizes one or more other columns. Resizing can also affect the position of the resized column. This option utilizes the full width of the table and ensures that no white space is added. A scrollbar appears only if all or most of the columns become to narrow. To avoid the side effect of undersized columns, you can set a minimum width per column. However, this minimum width is only taken into account if columns are resized automatically. End users can still reduce the column width to below the defined minimum (sap.ui.table.Column, properties: width, minWidth).

Users can rearrange columns by dragging the column header to another position (sap.ui.table.AnalyticalTable, property: enableColumnReordering). Keyboard interaction: Ctrl+Left and Ctrl+Right move the focused column header one position in the corresponding direction.

Column header

Opening the column header menu on touch devices

Columns do not use up the available space

Column Header Menu

For each column, a menu can contain the following menu items (sap.ui.table.AnalyticalColumnMenu, property: Visible):

Sort Ascending/Descending (sap.ui.table.AnalyticalColumn, property: showSortMenuEntries)
Free text filter (sap.ui.table.AnalyticalColumn, property: showFilterMenuEntries)
Group
Totals
Freeze from the first to the last specified column (sap.ui.table.AnalyticalTable, property: enableColumnFreeze)

For each column, the menu can be replaced by an app-specific menu.

Column header menu

Sort

The column header menu can provide two sort options (sap.ui.table.AnalyticalColumn, properties: sortProperty, showSortMenuEntry):

Sort Ascending
Sort Descending

The user selects one of these options to sort the corresponding column accordingly (sap.ui.table.AnalyticalColumn, properties: sorted, sortOrder, sortProperty).

Sort settings in column header menu

Filter

The column header menu can provide a search field for entering free text (sap.ui.table.AnalyticalColumn, properties: filterProperty, showFilterMenuEntries).

If the user enters a term in the input field and triggers the search by pressing ENTER when the focus is on the filter input field, the analytical table is filtered by the corresponding column and value (sap.ui.table.AnalyticalTable, properties: filtered, filterProperty, filterValue, filterOperator, sap.ui.table.AnalyticalColumn, property: filterType).

Note that the filter may return zero results, in which case, the table might be empty.

General recommendations for filtering:

If filtering is a main use case, choose the filter bar or any other filtering UI over the built-in free text filter.
Only use the free text filter if filtering is a secondary use case and if the filter bar is too heavy.

Free text filter in column header menu

Group

The column header menu can provide the option to group by this column (sap.ui.table.AnalyticalColumn, property: sortProperty).

One group collects all items with the same value within the corresponding column.

Group setting in column header menu

If line items are grouped in a column, every group is provided with a collapsible or expandable group header (sap.ui.table.AnalyticalColumn, property: grouped). The header text consists of the column name and the value for the corresponding group (sap.ui.table.AnalyticalColumn, property: groupHeaderFormatter). Several grouping levels are possible.

The corresponding column can be hidden to avoid duplicates (sap.ui.table.AnalyticalColumn, property: showIfGrouped). Exercise caution when using this option since hiding the column changes the table layout and may lead to confusion.

Group headers and the corresponding columns are shown – The relevant data is duplicated

Group headers shown, the corresponding column hidden – No duplicates

Aggregation

The column header menu can provide the option to show or hide aggregation totals for this column.

Intermediate aggregations are shown at group level for the corresponding columns if the group contains more than one line item (sap.ui.table.AnalyticalColumn, property: summed).

The overall aggregation is shown in a row at the bottom of the analytical table when the column contains values for a single unit of measure.

Overall aggregation for a single unit of measure

When the column contains values for more than one unit of measure, a Show Details link is displayed in a row at the bottom of the table, for example, when the column contains multiple currencies.

The Show Details link opens a popover that lists the totals for each unit of measure.

Overall aggregation for multiple units of measure via the 'Show Details' link

Freeze Columns

The column header menu can provide the option to freeze columns (sap.ui.table.AnalyticalTable, property: enableColumnFreeze). Selecting Freeze freezes all columns up to the one in which the operation was triggered (sap.ui.table.AnalyticalTable, property: fixedColumnCount).

When Freeze is triggered, the menu item changes to Unfreeze for the corresponding column.

Freeze setting in column header menu

Line Item Level

A line item contains a set of cells and provides options for selecting the item.

To prevent adverse side effects when scrolling vertically, all line items must have the same height.

(sap.ui.table.AnalyticalTable, property: rowHeight)

Line item

Drag and Drop

One or several items can be moved to other UI elements using drag and drop operations (sap.ui.table.AnalyticalTable, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop

Whole item as drop target

Cell Level

A cell provides one data point.

It can contain one of the following controls to display this data point:

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 with alignment, condensed mode, screen reader support, and keyboard support.

If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false). Do not wrap.

Cell

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows (like group headers). Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

By default, the analytical table provides a context menu on the group headers (for example, Expand, Collapse, …). Otherwise, no default context menus are provided.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or Shift+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Analytical table with context menu

Guidelines

Data Density vs. Complexity

The analytical table can be used to display and work with large amounts of data. Unfortunately, the analytical table has a high data density and therefore conveys an immediate feeling of complexity.

Only show tables with a lot of data as a last resort. To make the data easier to read, you should instead try the following:

Break down the data into manageable chunks and allow the user to navigate or drill down between them.
Use charts with drilldown functionality until the amount of data is more manageable.

Try to avoid horizontal scrolling in the default delivery.

Try to minimize the number of columns, especially if there is a large number of rows.

Table Title

Implement the table title by using a title control in a toolbar.

Use a table title only if the title of the table is not indicated in the surrounding area.

Do not use a table title if it simply repeats text that is already above the table. For example:

A pricing conditions table is the only control on a tab labeled Pricing Conditions.
A section or subsection on an object page contains only one table.

Use a table title if you need the item count, table toolbar, or variant management. To avoid repeating text, feel free to use generic text as a table title, such as Items.
Exception: If the surrounding area contains the table title, and both the item count and toolbar can be added to the surrounding area, no additional table title is needed.
Example: An object page (sub-)section contains only one table. In this case, add the item count and the table toolbar to the (sub-)section header.

If you use a table title, show either a title for the table, with or without variant management, or an item count in the following format:

Items (2,534).

The item count in the table title includes all the visible items that a user can reach by scrolling or expanding groups. Group headers are not included.

Remove the item count in the table title if there are zero items.

Developer Hint

Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table.

If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

Selection

Single Selection

For single-selection 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).
When setting a limit, also display the corresponding message when the user selects more items at once than the limit allows (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification).

In multiple selection mode (multi toggle), do not show checkboxes in the first data column in the default delivery to avoid confusion.

Don't

Do not add checkboxes to the first column

Never disable the selection checkbox. If an action can’t be performed on a specific item, inform the user after the corresponding action has been triggered. For more information, see Enabling/Disabling Actions.

Loading Data

To indicate that the table is currently loading items, use the busy state (sap.ui.table.AnalyticalTable, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Errors and Warnings

To indicate that the table contains items with errors or warnings, show a message strip above the table. On the message strip, provide information about errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

To indicate an error in a single row, see Item States below.

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

Developer Hint

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

Table containing errors and warnings

Columns – Best Practices

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

By default, the analytical table assigns the same width to each column. We recommend overwriting this default to provide optimal space for your content (sap.ui.table.AnalyticalColumn, property: width).

If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the size of the browser window results in a scrollbar. If the user resizes a column, and the total width of all columns exceeds the table width, a scrollbar appears. If the columns do not take up the full table width, white space appears to the right of the last column.

If you define the column width as a percentage, resizing one column affects the width of several or all columns. Reducing the size of the browser window truncates the texts. This ensures that the columns fill up all the available space. A scrollbar appears only if width of all the columns still exceeds the table width after the automatic width adjustments. To avoid the side effect of undersized columns, you can set a minimum width per column. However, this this minimum width is only taken into account if columns are automatically resized. End users can still reduce the column width to below the defined minimum (sap.ui.table.Column, properties: width, minWidth).

If you set the column width to “auto”, the behavior is the same as for “percentage”. However, unlike “percentage”, “auto” distributes the columns equally.

To decide on how to set the column width (pixel/rem/em vs. percent/auto), keep the following in mind:

For tables with only 2 to 3 columns, use pixel-based units. This ensures that the values in the columns are not spread over the whole screen on wide screens, which improves the readability of the line items.
For tables with many columns, where a horizontal scrollbar is usually needed, use pixel based units. This avoids unintended side effects when resizing columns.
For all other tables, use whatever fits your case better.

Be cautious when mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it can also cause even more side effects when resizing a column. If you are using percentage-based widths for one or more columns, consider not allowing end users to resize columns at all.

Optimize the column width for its initial visible content, including the column header texts. If this is not possible (for example, if showing the full texts would result in extremely wide columns), let the texts truncate. End users can change the width of the column to read the full text, as needed.

Maintain a constant column width and avoid adjusting it automatically when the content changes.

Always keep to one line of text. Do not wrap.

Don't

Don't truncate the initial visible content In the default delivery

Don't

Never wrap texts

Column Headers – Best Practices

For each column, provide a label in the column header. In the default delivery, do not truncate the column header texts. Only let the text truncate if showing the full text would make the column too wide. Never wrap the text.

Content Alignment

For alignment of cell content, follow the guidelines below.

Left-align: text, IDs, phone numbers, URLs, passwords, and email addresses.

Left-alignment of text

Right-align: numbers, except IDs, to ensure comparability of numbers and amounts.

Right-alignment of numbers

Right-align amounts with currencies to the cell and align their respective decimal points.

This ensures that amounts with different currencies are shown correctly, regardless of whether the currencies have 0, 2, or 3 decimals.

For aligning to the decimal point, use the sap.ui.uinified.Currency control.

Alignment to the decimal point

Right-align dates and times.

This ensures comparability for most formats and locales.

Right-alignment of dates

Left-align status information.

Left-align status information

Center-align icons.

Left-align micro charts.

XS micro charts in condensed mode

Content Formatting

Key Identifier

Use a bold label or an emphasized link as the key identifier of an item. In the default delivery, show the key identifier in the first column.

Emphasized link

For strings with IDs, use one of the following:

Show the ID in a separate column. Use this format if users need to sort, group, or filter by both the string and the ID.
Show the ID in parentheses after the corresponding string. In this case, you must opt for one criterion for sorting, filtering, and grouping – either the string or the ID. This option is then used for all sort, filter and group actions and can’t be changed later by the user. Use this format only if users don’t need to sort, filter, and group by both the string and the ID.

Text and ID in two columns – Allows sorting, filtering, and grouping for both

If displayed as a link, use only the string as the link, not the ID

Text and ID in one column – Sorting, filtering, and grouping are available for either the text or the ID, but not for both

If displayed as a link, use the whole text as the link

Truncation

Avoid truncation of typical content in the default delivery (sap.ui.table.AnalyticalColumn, property: width). However, since the columns are resizable, do not worry too much if truncation occurs as columns can still be enlarged if necessary.

To prevent adverse side effects when scrolling vertically, all line items must also have the same height. If you need to decide between truncation and different row heights, choose truncation. Do not wrap.

Optimize column width for typical content, not all content

Number of Links

Are there too many links? Use subtle links to avoid a wall of links. Standard links are also emphasized more if they are surrounded by subtle links.

For example, a financial table consists of several columns with summarized cells. A summarized cell shows the total sum of several database entries. Each sum should be a link to a report that shows details about which database entries produce the total sum. The line item identifier should also be a link that provides more detail about the line item itself. Use a standard or emphasized link for the item identifier, and subtle links for the summarized cells.

Emphasized links, links, subtle links, and text

Missing Value

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

Leave empty fields blank

Numbering Items

In terms of numbering items:

If the item number is more like an ID with regard to its description, use ID formatting as described above.
In all other cases, use a separate column for the item number.

Add a separate column for the item number

Status

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

For status information on text, use an object status.

Semantic colors on text

Micro Charts

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

Micro charts in an analytical table

Empty Tables

Avoid empty analytical tables. If necessary, provide instructions on how to fill the analytical table with data (sap.ui.table.AnalyticalTable, properties: noDataText, showNoData).

Examples:

If a table is initially empty, provide at least a basic text:
No items available.
Overwrite this whenever a hint can be provided on how to fill the table with data.
If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
To start, set the relevant filters.
If a table is used together with a filter bar and the filter does not return results, use the following text:
No data found. Try adjusting the filter settings.

Adapt the texts above if:

The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
The standard text is misleading (for example, if the data is filled based on a list-detail pattern instead of filter settings).

Provide meaningful instructions

Invalid State

To show an invalid state of the analytical table within the list report floorplan, show an overlay on the analytical table and the corresponding toolbar (sap.ui.table.AnalyticalTable, property: showOverlay). The overlay prevents user interactions.

Use this within the list report floorplan if filter settings have been changed but the analytical table has not yet been updated.

Analytical table with invalid data

Item States

To show that an item has been modified, for example, within the global edit flow, add the string (Modified) in an additional column with the label Editing Status.

In the default delivery, add a column directly behind the key identifier.

A modified item

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.

A modified item with an error

To show that an item is locked, add a transparent-style button with the corresponding icon and the text Locked by [name] in the Editing Status column.

A locked item

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

Item in draft state

Show only one state at a time.

Numbers and Units

Show the unit of measurement in one of the following ways:

The number and unit are in the same cell. Do this if sorting, filtering, or grouping by the unit of measurement are not needed.

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

Number and unit of measurement in one cell

The number and unit are in separate columns. Do this if sorting, filtering, or grouping by the unit of measurement are a common use case.

Note that this column can be hidden or moved independently of the column containing the corresponding number. Therefore, be sure to have clear labels for both columns to communicate the dependency.

Number and unit of measurement in two columns

If the unit of measurement is the same for all rows, show the unit of measurement in the column header. Otherwise, show the unit of measurement within the row.

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items. These are keyboard operable and available on all browsers.

Use drag and drop only in addition to existing visible UI elements

Do not use drag and drop for rearranging items in the analytical table. The analytical table is mainly used for grouping items and for calculating the totals per group and column. Moving items to another group also means that a value of the dropped item changes: because grouping is based on values in a column, the dropped item needs to take on the value of the target group for the corresponding column.

Example:
A table is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. Because changing the value in this way doesn’t make sense, rearranging items is not permitted in analytical tables.

Don't

Do not use drag and drop for rearranging items in the analytical table

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar). Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

The context menu can be triggered for the table, row, or cell. However, we do not recommend using context menus for cells: because the content of a cell is a different touch target than the cell itself, opening a cell context menu via touch is quite hard, even in cozy mode.

Do not combine context menus with condensed mode: editable controls fill the entire space inside a cell. Because of this, context menus cannot be opened at all with touch or mouse interaction.

Actions

Multiple Items

To trigger actions on multiple items, use a multiselection analytical table (sap.ui.table.AnalyticalTable, property: selectionMode, value: MultiToggle). Offer the corresponding actions in the table toolbar.

Do not offer action triggering on multiple items if the table is generally expected to have fewer than 10 items. In this case, try to use the responsive table instead of the analytical table.

Single Item

To trigger actions on a single item (sap.ui.table.AnalyticalTable, property: selectionMode, value: Single):

Show the actions on the table toolbar.
In rare cases, show the actions within the line item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. Provide a separate column per action. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

Single Cell

To trigger actions on a single cell, create the corresponding click event. Do not use the cell click event if the cell contains interactive controls, such as links.

To trigger navigation on line item level choose one of the following options:

Use a link for the attribute that identifies the row. Clicking the link triggers the navigation.
Add the RowActions column and show the navigation indicator ( ) at the end of the row. The navigation arrow triggers the navigation.

Special case: Multi-selection in a 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.

Navigate to details page

Single Cell

For triggering actions on a single cell, create the corresponding click event. Do not use the cell click event if the cell contains interactive controls, such as links.

Add Items

To let users add items, place an Add or Create text button on the table toolbar.

Use Create if the button adds a brand new item that doesn’t yet exist on the database.
Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the table, with a visual highlight at the beginning of the row.

Enable the shortcut Ctrl+Enter (and ideally also Enter) to trigger the Add or Create button.

There are three options for adding an item. In order of priority (most recommended first), these are:

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.
Open a dialog for larger tables with up to 8 editable columns. Save the new item at the dialog level.
Navigate to a new page. Only use this option for very complex scenarios that cannot be handled by a dialog (for example, tables with more than 8 columns). When the user presses Save in the footer toolbar of the create page, navigate back to the table.

Depending on the flow, an item can be in one of three different states:

New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item in the table. Ignore current sort, filter and grouping criteria to keep the item visible.
Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is applied as follows:
- Inline creation: After Save is triggered on the table toolbar or at page level.
- Create with dialog: A table showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

If draft handling is used, new items are not saved at table level, but rather with the entire draft.

For more details, see the guidelines for managing objects (including subarticles).

Editable Content

For editable content, only use the following controls, and only one control per cell:

Only these controls are optimized for all viewing modes of the analytical table.

If you need edit mode, change your text controls, such as label, text, link, object status, icons, and currencies, to editable controls as soon as you switch to edit mode, but not before. You can do this by exchanging the controls, for example, from sap.m.Text to sap.m.Input.

For mass editing items:

Provide multiselection.
Provide an Edit button.
If several items are selected, clicking the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

This is similar to mass editing in the split-screen layout floorplan.

Warning

Do not offer editing for summarized cells. A summarized cell shows the total sum of several database entries. Changing the total sum does not make sense since it is unclear how this sum is divided between the different database entries.

Interactive controls – Inline

View Settings

There are several ways to show Sort, Filter, and/or Group settings:

Column header menu: In all cases, show the corresponding settings in the column header menu.
View settings dialog: Simple and more flexible with regard to filter settings. No advantage for sorting. Allows the user to ungroup grouped columns.tables with a medium amount of items.
Table personalization dialog: Provides complex options for sorting items by several levels and allows the user to ungroup grouped columns. It also provides a query-builder-like approach for filter settings. The complexity of the options is also its downside. Use the table personalization dialog for tables with a large number of items.
If filtering is a main use case, use the filter bar. In this case, avoid offering additional filter settings on the table. If you do, the filter settings on the table work only on the result set provided by the filter bar.

Always be careful when synchronizing the settings in the dialog with the settings from the column header menu.

Trigger the dialogs in one of the following ways:

View settings dialog: Provide several buttons, one for each of these view settings. Each button opens the view settings dialog on the corresponding page.
Table personalization dialog: Provide a settings button, which opens the table personalization dialog containing all pages.

Use only the view settings you really need. For example, do not offer grouping if it does not support your use case.

Column header menu with view settings

Table toolbar with triggers for view settings dialog

Table toolbar with trigger for table personalization dialog

Persist the view settings. When a user reopens the app, show the analytical table with the same sort, filter, group, and aggregation settings as last defined by this user.

Sort

Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the first column in the default delivery.

To display the current sort state, an icon is shown in the column header of the last sorted column. This icon indicates the sort direction (sap.ui.table.AnalyticalColumn, properties: sorted, sortOrder, sortProperty).

For the default sort setting, sort by the column that identifies the row, which is usually the first column in default delivery. Use a meaningful sort order, such as alphabetical order for text, numeric order for numbers, or chronological order for dates.

Column, sorted ascending

Column, sorted descending

The descending sort order must always be the exact reverse of the ascending sort order.

For each column, provide a meaningful sort order. For example:

Sort text alphabetically
Sort numbers by their value
Sort status information by the severity of the status:
- Ascending: Sort status information from positive to negative, with neutral last.
- Descending: Sort status information from negative to positive, with neutral first.

Object status sorted ascending, with neutral status last

Object status sorted descending, with neutral status first

- Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
- Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Object status sorted ascending and alphabetically, from positive to negative with neutral last

Object status sorted descending and alphabetically, from negative to positive with neutral first

Filter

To display the current filter state, an icon is shown in the column header of the filtered column (sap.ui.table.AnalyticalColumn, properties: filtered, filterProperty, filterValue, filterOperator, defaultFilterOperator, filterType).

Column, filtered

Group

To display the current group state, group headers are shown. Show the following text in the group header (sap.ui.table.AnalyticalColumn, properties: grouped, showIfGrouped, groupHeaderFormatter):

[Label of the grouped column]: [Grouping value]

If there is no grouping value, show the following text:
[Label of the grouped column]: (Not Available)

This is the case if you have a group of items that don’t have a value for the grouped column.

Set the property collapseRecursive to “false” to keep subgroups expanded even after collapsing and expanding the parent group.

Group headers, several levels

On non-touch devices, right-clicking a group header opens the group header menu. On touch devices, the same menu is opened by using the menu icon on the right side of a group header.

The group header menu provides several options:

Show/Hide: Shows or hides the column in the table layout, although it is grouped.
Ungroup: When the user ungroups a column, the corresponding group headers disappear. If the column was hidden, it is shown again as a separate column.
Ungroup All: The columns are shown again.
Move Up: Rearranges the grouping levels hierarchy by moving the selected group above the group that is one level higher up in the hierarchy.
Move Down: Rearranges the grouping levels hierarchy by moving the selected group below the group that is one level lower down in the hierarchy.
Collapse Level: Collapses all groups on the corresponding grouping level.
Collapse All: All groups are collapsed.

Group header menu

Group header on touch devices

In general:

Offer grouping on objects and attributes.
Do not offer grouping on measures.
If appropriate, offer reasonable grouping by default, but do not exaggerate. As a rule of thumb, use up to three group levels.
Provide more space for the first column. Grouping needs an indent per group level. Extra space in the first column prevents truncated text.

Aggregate

To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.

If items are grouped, an intermediate sum is shown:

At the bottom of each group if the group is expanded.
In the group header if the group is collapsed.

(sap.ui.table.AnalyticalColumn, property: summed)

When aggregating amounts with different units of measurement, show an asterisk (*) in the aggregation rows.

When sorting an aggregated column, only the leaf nodes of a group are included by default. If each measure column currently displays a single unit of measurement, the order of the groups can also be affected.

For example:
Let’s assume that table items are grouped by Country/Region and aggregated by Total Net Amount. If you sort the Total Net Amount column in descending order, the largest total net amount is shown first.

Warning

Only enable sorting by totals if each column has a single unit of measurement. This prevents inconsistencies in the sorting behavior, which depends on user settings, such as filter settings or the columns currently displayed.

Developer Hint

To allow sorting by totals, the following conditions must be met:

For each measure column, multiple units must not occur in the displayed data, regardless of whether or not totals are shown.
The autoExpandMode of the AnalyticalBinding must be set to Sequential. Note that the default is Bundled.

In general:

Offer aggregation on measures, but not on objects or attributes.
Avoid aggregations on the first three columns for the default delivery. As soon as grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.
Where appropriate, offer reasonable aggregation by default.

Aggregation and groups

Personalization

Only offer personalization if you need more columns than a tablet screen can display at any one time, which is usually five.

Persist the column layout. When a user reopens the app, show the analytical table with the same column layout settings as last defined by this user.

Add, Remove, and Rearrange Columns

To add, remove, or rearrange columns, use one of the following:

The table personalization dialog: It offers some simple settings for column layout. Use this if you have only a few columns to choose from and/or you use the view settings dialog.
The p13n dialog: Besides various complex view settings, it also provides settings for column layout. Use this if you have a large number of columns to choose from and/or you use this dialog anyway for view settings.

In both cases, trigger the dialog via the settings button in the table toolbar. As short cut, use CTRL+COMMA.

You can also use drag and drop to rearrange columns (sap.ui.table.Table, property: enableColumnReordering). If you allow rearranging via drag and drop as well as via a dialog, keep both places in sync.

Resize Columns

Resizing columns works differently on touch and non-touch devices.

Non-touch devices: Drag and drop the column separator on the right side of the column. Double-clicking the column separator optimizes the width of the column for the data currently loaded into the front end, which is usually about 100 rows.
Touch devices: Clicking the column header reveals two buttons: one for opening the column header menu, another one for resizing the column. Drag and drop this second button to resize the column.

Freeze Columns

For freezing columns, offer the setting in the column header menu (sap.ui.table.AnalyticalTable, property: enableColumnFreeze).

Selecting Freeze on a column freezes all columns from the first one to the one where Freeze is selected. On this column, the menu entry changes from Freeze to Unfreeze.

Frozen column

Highlight Items

To show that an item needs attention, you can display a highlight indicator in front of the item. The highlight indicator can be used to indicate:

A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.ui.table.AnalyticalTable, aggregation: rowSettingsTemplate)

Highlighted items

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 tables. We advise using 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.

'Export to Spreadsheet' menu button

Properties

sap.ui.table.AnalyticalTable

The following additional properties are available for the analytical table:

The property: width defines the width of the analytical table.
The property: rowHeight defines the height of each row in the analytical table. Since the height required is calculated automatically by the analytical table, this property is only needed rarely.
The property: columnHeaderHeight defines the height of the column headers. Since the height required is calculated automatically by the analytical table, this property is only needed rarely.
The property: columnHeaderVisible can be used to hide the column headers. Always show the column headers.
The property: showColumnVisibilityMenu provides an additional entry in the column header menu that allows columns to be shown or hidden. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
The property: columnVisibilityMenuSorter is used for sorting the columns inside the column header menu if showing and hiding columns is provided in the menu. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
The property: visibleRowCount defines the height of the analytical table. Show as many rows as fit on the screen.
The property: visibleRowCountMode defines whether the height of the analytical table is fixed or automatically calculated based on the space provided by the underlying container. For automatic calculation, make sure that all rows have the same height.
The property: minimumAutoRowCount defines the minimum number of rows that must be shown if the property: visibleRowCountMode is set to “auto”. Show at least three to five rows.
The property: firstVisibleRow defines the first row shown in the visible area of the analytical table. The analytical table is scrolled accordingly.
The property: allowColumnReordering is deprecated. Use the property: enableColumnReordering instead.
The property: editable does not have a visible effect. Please do not use it.
The property: threshold is used for optimizing lazy loading of items. In most cases, the default value is appropriate.
The property: enableGrouping is experimental and does not have a meaningful effect on the analytical table. Do not use it.
The property: sumOnTop shows additional aggregation values on the group header, even if the group is expanded. Do not use it.
The property: enableCustomFilter changes the filter entry in the column header menu from an edit box to Filter…. Selecting this entry throws an event that apps can react to, for example, by opening a dialog. In general, you should choose the built-in filter over your own implementation. Specifically, keep filtering via the column header menu simple, while offering more advanced options via the table personalization dialog.
The property: enableBusyIndicator has not yet been fully implemented. Do not use it.
The property: title adds a line of text on top of the analytical table. Do not use it. To add a title to the table, use a toolbar.
The property: footer adds a short text at the bottom of the table.
The property: Busy sets the analytical table to busy state. While in busy state, the whole table cannot be used and items cannot be read due to an overlay.
The property: Tooltip does not have an effect. Do not use it.
The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). Do not use it.

sap.ui.table.AnalyticalColumn

The following additional properties are available for the analytical column:

The property: leadingProperty is used for data binding.
The property: inResult is used for data binding.
The property: visible defines whether a column is shown or hidden.
The property: name defines the name shown in the column header menu for showing and hiding columns. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Please do not use this property.
The property: headerSpan defines whether one column header is used for one or several columns. To prevent adverse side effects, always use one column header for only one single column. Please do not use this property.
The property: Tooltip does not have an effect. Please do not use it.

Resources

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

Elements and Controls

Bullet Micro Chart (guidelines)
Comparison Micro Chart (guidelines)
Feed List Item (guidelines)
Grid Table (guidelines)
Link (guidelines)
List Report Floorplan (guidelines)
Multi-Input Field (guidelines)
Responsive Table (guidelines)
Stacked Bar Micro Chart (guidelines)
Table Personalization Dialog (guidelines)
Table Toolbar (guidelines)
Tree Table (guidelines)
Variant Management (guidelines)
View Settings Dialog (guidelines)

Implementation

Analytical Table (SAPUI5 API reference)
Analytical Column (SAPUI5 API reference)
Analytical Column Menu (SAPUI5 API reference)

Chart Color Palettes – Values and Names

This page provides all the color token names that are intended for use in all SAP chart palettes.

Extended chart colors

Use of Tokens

Do

Use token/variable names.

Don't

Don’t use HEX values!

To support cross-technology chart implementation and theming capabilities, styles are defined by token names. Tokens ensure that values can be implemented centrally for multiple usages. This is explained in detail in the design token guidelines.

The associated HEX values shown on this page are for the Morning Horizon theme and should not be implemented directly in any implementation!

Values for the theming tokens for all themes are available within the directories of the open-sourced SAP Base Theming Content repository. Also check out the guidelines for design tokens and theming.

Qualitative Palette

Qualitative Palette with Base Chart Color Tokens

The base chart colors are intended to be used across all of the SAP technologies. The value of sapChart_OrderedColor_1 (and the corresponding sapChart_Sequence_1) is used as the default color across chart libraries. All of the ordered tokens are used as base values for all chart palettes. The technical ordering of the chart colors may vary between chart libraries depending on the context. It is, however, important that the correct theming tokens are used to ensure consistency.

Token Name	Morning Horizon
sapChart_OrderedColor_1		#3278be
sapChart_OrderedColor_2		#c87b00
sapChart_OrderedColor_3		#75980b
sapChart_OrderedColor_4		#df1278
sapChart_OrderedColor_5		#8b47d7
sapChart_OrderedColor_6		#049f9a
sapChart_OrderedColor_7		#0070f2
sapChart_OrderedColor_8		#cc00dc
sapChart_OrderedColor_9		#798c77
sapChart_OrderedColor_10		#da6c6c
sapChart_OrderedColor_11		#5d36ff
sapChart_OrderedColor_12		#a68a5b

Sequential Palette

Chart Sequence Colors

Chart sequence colors are connected to the main chart ordered colors. For example, sapChart_OrderedColor_1 is used as the value for sapChart_Sequence_1. The other sequence colors are then calculated to be either lighter (plus) or darker (minus) versions of sapChart_Sequence_1. This simple color relationship logic makes colors easy to modify for themeability, allowing SAP to update any token centrally and also provide future-friendly theme compatibility across all SAP technologies.

Chart Sequence Color 1

Color Name	Morning Horizon
sapChart_Sequence_1_Plus3		#84b8eb
sapChart_Sequence_1_Plus3_TextColor		#000000
sapChart_Sequence_1_Plus2		#468acd
sapChart_Sequence_1_Plus2_TextColor		#000000
sapChart_Sequence_1_Plus1		#3c8cdd
sapChart_Sequence_1_Plus1_TextColor		#000000
sapChart_Sequence_1		#3278be
sapChart_Sequence_1_TextColor		#ffffff
sapChart_Sequence_1_Minus1		#31669c
sapChart_Sequence_1_Minus1_TextColor		#ffffff
sapChart_Sequence_1_Minus2		#31669c
sapChart_Sequence_1_Minus2_TextColor		#ffffff
sapChart_Sequence_1_Minus3		#204060
sapChart_Sequence_1_Minus3_TextColor		#ffffff
sapChart_Sequence_1_Minus4		#19334e
sapChart_Sequence_1_Minus4_TextColor		#ffffff
sapChart_Sequence_1_Minus5		#13263a
sapChart_Sequence_1_Minus5_TextColor		#ffffff

Chart Sequence Color 2

Color Name	Morning Horizon
sapChart_Sequence_2_Plus3		#efbf72
sapChart_Sequence_2_Plus3_TextColor		#000000
sapChart_Sequence_2_Plus2		#eaaa44
sapChart_Sequence_2_Plus2_TextColor		#000000
sapChart_Sequence_2_Plus1		#e29419
sapChart_Sequence_2_Plus1_TextColor		#000000
sapChart_Sequence_2		#c87b00
sapChart_Sequence_2_TextColor		#000000
sapChart_Sequence_2_Minus1		#9f6200
sapChart_Sequence_2_Minus1_TextColor		#ffffff
sapChart_Sequence_2_Minus2		#7c4c00
sapChart_Sequence_2_Minus2_TextColor		#ffffff
sapChart_Sequence_2_Minus3		#623c00
sapChart_Sequence_2_Minus3_TextColor		#ffffff
sapChart_Sequence_2_Minus4		#623c00
sapChart_Sequence_2_Minus4_TextColor		#ffffff
sapChart_Sequence_2_Minus5		#2f1d00
sapChart_Sequence_2_Minus5_TextColor		#ffffff

Chart Sequence Color 3

Color Name	Morning Horizon
sapChart_Sequence_3_Plus3		#b9d369
sapChart_Sequence_3_Plus3_TextColor		#000000
sapChart_Sequence_3_Plus2		#a6c742
sapChart_Sequence_3_Plus2_TextColor		#000000
sapChart_Sequence_3_Plus1		#8fad33
sapChart_Sequence_3_Plus1_TextColor		#000000
sapChart_Sequence_3		#75980b
sapChart_Sequence_3_TextColor		#000000
sapChart_Sequence_3_Minus1		#587208
sapChart_Sequence_3_Minus1_TextColor		#ffffff
sapChart_Sequence_3_Minus2		#3e5106
sapChart_Sequence_3_Minus2_TextColor		#ffffff
sapChart_Sequence_3_Minus3		#2c3904
sapChart_Sequence_3_Minus3_TextColor		#ffffff
sapChart_Sequence_3_Minus4		#212b03
sapChart_Sequence_3_Minus4_TextColor		#ffffff
sapChart_Sequence_3_Minus5		#161c02
sapChart_Sequence_3_Minus5_TextColor		#ffffff

Chart Sequence Color 4

Color Name	Morning Horizon
sapChart_Sequence_4_Plus3		#f473b3
sapChart_Sequence_4_Plus3_TextColor		#000000
sapChart_Sequence_4_Plus2		#f14d9e
sapChart_Sequence_4_Plus2_TextColor		#000000
sapChart_Sequence_4_Plus1		#ee278a
sapChart_Sequence_4_Plus1_TextColor		#000000
sapChart_Sequence_4		#df1278
sapChart_Sequence_4_TextColor		#ffffff
sapChart_Sequence_4_Minus1		#b90f64
sapChart_Sequence_4_Minus1_TextColor		#ffffff
sapChart_Sequence_4_Minus2		#930c4f
sapChart_Sequence_4_Minus2_TextColor		#ffffff
sapChart_Sequence_4_Minus3		#770a40
sapChart_Sequence_4_Minus3_TextColor		#ffffff
sapChart_Sequence_4_Minus4		#51072c
sapChart_Sequence_4_Minus4_TextColor		#ffffff
sapChart_Sequence_4_Minus5		#3a051f
sapChart_Sequence_4_Minus5_TextColor		#ffffff

Chart Sequence Color 5

Color Name	Morning Horizon
sapChart_Sequence_5_Plus3		#d5bcf0
sapChart_Sequence_5_Plus3_TextColor		#000000
sapChart_Sequence_5_Plus2		#b994e0
sapChart_Sequence_5_Plus2_TextColor		#000000
sapChart_Sequence_5_Plus1		#a679d8
sapChart_Sequence_5_Plus1_TextColor		#000000
sapChart_Sequence_5		#8b47d7
sapChart_Sequence_5_TextColor		#ffffff
sapChart_Sequence_5_Minus1		#7236b5
sapChart_Sequence_5_Minus1_TextColor		#ffffff
sapChart_Sequence_5_Minus2		#5e2c96
sapChart_Sequence_5_Minus2_TextColor		#ffffff
sapChart_Sequence_5_Minus3		#522682
sapChart_Sequence_5_Minus3_TextColor		#ffffff
sapChart_Sequence_5_Minus4		#46216f
sapChart_Sequence_5_Minus4_TextColor		#ffffff
sapChart_Sequence_5_Minus5		#341358
sapChart_Sequence_5_Minus5_TextColor		#ffffff

Chart Sequence Color 6

Color Name	Morning Horizon
sapChart_Sequence_6_Plus3		#64ede9
sapChart_Sequence_6_Plus3_TextColor		#000000
sapChart_Sequence_6_Plus2		#2ee0da
sapChart_Sequence_6_Plus2_TextColor		#000000
sapChart_Sequence_6_Plus1		#05c7c1
sapChart_Sequence_6_Plus1_TextColor		#000000
sapChart_Sequence_6		#049f9a
sapChart_Sequence_6_TextColor		#000000
sapChart_Sequence_6_Minus1		#02837f
sapChart_Sequence_6_Minus1_TextColor		#ffffff
sapChart_Sequence_6_Minus2		#006663
sapChart_Sequence_6_Minus2_TextColor		#ffffff
sapChart_Sequence_6_Minus3		#00514f
sapChart_Sequence_6_Minus3_TextColor		#ffffff
sapChart_Sequence_6_Minus4		#003d3b
sapChart_Sequence_6_Minus4_TextColor		#ffffff
sapChart_Sequence_6_Minus5		#002322
sapChart_Sequence_6_Minus5_TextColor		#ffffff

Chart Sequence Color 7

Color Name	Morning Horizon
sapChart_Sequence_7_Plus3		#68aeff
sapChart_Sequence_7_Plus3_TextColor		#000000
sapChart_Sequence_7_Plus2		#4098ff
sapChart_Sequence_7_Plus2_TextColor		#000000
sapChart_Sequence_7_Plus1		#1c85ff
sapChart_Sequence_7_Plus1_TextColor		#000000
sapChart_Sequence_7		#0070f2
sapChart_Sequence_7_TextColor		#ffffff
sapChart_Sequence_7_Minus1		#0062d3
sapChart_Sequence_7_Minus1_TextColor		#ffffff
sapChart_Sequence_7_Minus2		#0054b5
sapChart_Sequence_7_Minus2_TextColor		#ffffff
sapChart_Sequence_7_Minus3		#00418c
sapChart_Sequence_7_Minus3_TextColor		#ffffff
sapChart_Sequence_7_Minus4		#00244f
sapChart_Sequence_7_Minus4_TextColor		#ffffff
sapChart_Sequence_7_Minus5		#001b3a
sapChart_Sequence_7_Minus5_TextColor		#ffffff

Chart Sequence Color 8

Color Name	Morning Horizon
sapChart_Sequence_8_Plus3		#f462ff
sapChart_Sequence_8_Plus3_TextColor		#000000
sapChart_Sequence_8_Plus2		#f034ff
sapChart_Sequence_8_Plus2_TextColor		#000000
sapChart_Sequence_8_Plus1		#ed0bff
sapChart_Sequence_8_Plus1_TextColor		#000000
sapChart_Sequence_8		#cc00dc
sapChart_Sequence_8_TextColor		#ffffff
sapChart_Sequence_8_Minus1		#a600b3
sapChart_Sequence_8_Minus1_TextColor		#ffffff
sapChart_Sequence_8_Minus2		#80008a
sapChart_Sequence_8_Minus2_TextColor		#ffffff
sapChart_Sequence_8_Minus3		#6d0076
sapChart_Sequence_8_Minus3_TextColor		#ffffff
sapChart_Sequence_8_Minus4		#56005d
sapChart_Sequence_8_Minus4_TextColor		#ffffff
sapChart_Sequence_8_Minus5		#350039
sapChart_Sequence_8_Minus5_TextColor		#ffffff

Chart Sequence Color 9

Color Name	Morning Horizon
sapChart_Sequence_9_Plus3		#bdc6bc
sapChart_Sequence_9_Plus3_TextColor		#000000
sapChart_Sequence_9_Plus2		#b5bfb4
sapChart_Sequence_9_Plus2_TextColor		#000000
sapChart_Sequence_9_Plus1		#97a695
sapChart_Sequence_9_Plus1_TextColor		#000000
sapChart_Sequence_9		#798c77
sapChart_Sequence_9_TextColor		#000000
sapChart_Sequence_9_Minus1		#667664
sapChart_Sequence_9_Minus1_TextColor		#ffffff
sapChart_Sequence_9_Minus2		#536051
sapChart_Sequence_9_Minus2_TextColor		#ffffff
sapChart_Sequence_9_Minus3		#404a3f
sapChart_Sequence_9_Minus3_TextColor		#ffffff
sapChart_Sequence_9_Minus4		#2d342c
sapChart_Sequence_9_Minus4_TextColor		#ffffff
sapChart_Sequence_9_Minus5		#1e231e
sapChart_Sequence_9_Minus5_TextColor		#ffffff

Chart Sequence Color 10

Color Name	Morning Horizon
sapChart_Sequence_10_Plus3		#f1c6c6
sapChart_Sequence_10_Plus3_TextColor		#000000
sapChart_Sequence_10_Plus2		#eaadad
sapChart_Sequence_10_Plus2_TextColor		#000000
sapChart_Sequence_10_Plus1		#e28d8d
sapChart_Sequence_10_Plus1_TextColor		#000000
sapChart_Sequence_10		#da6c6c
sapChart_Sequence_10_TextColor		#000000
sapChart_Sequence_10_Minus1		#b75757
sapChart_Sequence_10_Minus1_TextColor		#000000
sapChart_Sequence_10_Minus2		#9d4343
sapChart_Sequence_10_Minus2_TextColor		#ffffff
sapChart_Sequence_10_Minus3		#803737
sapChart_Sequence_10_Minus3_TextColor		#ffffff
sapChart_Sequence_10_Minus4		#672c2c
sapChart_Sequence_10_Minus4_TextColor		#ffffff
sapChart_Sequence_10_Minus5		#562424
sapChart_Sequence_10_Minus5_TextColor		#ffffff

Chart Sequence Color 11

Color Name	Morning Horizon
sapChart_Sequence_11_Plus3		#c0b0ff
sapChart_Sequence_11_Plus3_TextColor		#000000
sapChart_Sequence_11_Plus2		#9b83ff
sapChart_Sequence_11_Plus2_TextColor		#000000
sapChart_Sequence_11_Plus1		#8669ff
sapChart_Sequence_11_Plus1_TextColor		#000000
sapChart_Sequence_11		#5d36ff
sapChart_Sequence_11_TextColor		#ffffff
sapChart_Sequence_11_Minus1		#4b25e7
sapChart_Sequence_11_Minus1_TextColor		#ffffff
sapChart_Sequence_11_Minus2		#3a17cd
sapChart_Sequence_11_Minus2_TextColor		#ffffff
sapChart_Sequence_11_Minus3		#2f13a8
sapChart_Sequence_11_Minus3_TextColor		#ffffff
sapChart_Sequence_11_Minus4		#250f83
sapChart_Sequence_11_Minus4_TextColor		#ffffff
sapChart_Sequence_11_Minus5		#2f13a8
sapChart_Sequence_11_Minus5_TextColor		#ffffff

Chart Sequence Color 12

Color Name	Morning Horizon
sapChart_Sequence_12_Plus3		#e4ddcf
sapChart_Sequence_12_Plus3_TextColor		#000000
sapChart_Sequence_12_Plus2		#dacebb
sapChart_Sequence_12_Plus2_TextColor		#000000
sapChart_Sequence_12_Plus1		#c4b293
sapChart_Sequence_12_Plus1_TextColor		#000000
sapChart_Sequence_12		#a68a5b
sapChart_Sequence_12_TextColor		#000000
sapChart_Sequence_12_Minus1		#8c744c
sapChart_Sequence_12_Minus1_TextColor		#ffffff
sapChart_Sequence_12_Minus2		#786441
sapChart_Sequence_12_Minus2_TextColor		#ffffff
sapChart_Sequence_12_Minus3		#5e4e33
sapChart_Sequence_12_Minus3_TextColor		#ffffff
sapChart_Sequence_12_Minus4		#433825
sapChart_Sequence_12_Minus4_TextColor		#ffffff
sapChart_Sequence_12_Minus5		#30271a
sapChart_Sequence_12_Minus5_TextColor		#ffffff

Semantic Palette

Semantic Token Naming

The naming of the semantic tokens is generic and may not reflect usage within the charts. Application teams determine the contextual usage of chart colors.

Token Name	Morning Horizon
sapChart_Bad		#f53232
sapChart_Critical		#e26300
sapChart_Good		#30914c
sapChart_Neutral		#758ca4

Semantic Sequence Palette

Semantic Sequence Colors for Charts

Semantic sequence colors for charts are connected to the main semantic colors. For example, sapChart_Critical is used as the value for sapChart_Sequence_Critical. The other sequence colors are then calculated to be either lighter (plus) or darker (minus) versions of sapChart_Sequence_Critical. This simple color relationship logic makes colors easy to modify for themeability, allowing SAP to update any token centrally and also provide future-friendly theme compatibility across all SAP technologies.

The naming of semantic tokens is generic and may not reflect usage within the charts. Application teams determine the contextual usage of chart colors.

Chart Sequence Bad

Context examples: a bad or error value state context; heat; lifecycle contexts like negative, minus, overdue, or stopped

Chart Token	Morning Horizon
sapChart_Sequence_Bad_Plus3		#fdcece
sapChart_Sequence_Bad_Plus3_TextColor		#000000
sapChart_Sequence_Bad_Plus2		#fa9d9d
sapChart_Sequence_Bad_Plus2_TextColor		#000000
sapChart_Sequence_Bad_Plus1		#f86c6c
sapChart_Sequence_Bad_Plus1_TextColor		#000000
sapChart_Sequence_Bad		#f53232
sapChart_Sequence_Bad_TextColor		#000000
sapChart_Sequence_Bad_Minus1		#d00a0a
sapChart_Sequence_Bad_Minus1_TextColor		#ffffff
sapChart_Sequence_Bad_Minus2		#a90808
sapChart_Sequence_Bad_Minus2_TextColor		#ffffff
sapChart_Sequence_Bad_Minus3		#830606
sapChart_Sequence_Bad_Minus3_TextColor		#ffffff
sapChart_Sequence_Bad_Minus4		#570404
sapChart_Sequence_Bad_Minus4_TextColor		#ffffff
sapChart_Sequence_Bad_Minus5		#320000
sapChart_Sequence_Bad_Minus5_TextColor		#ffffff

Chart Sequence Critical

Context examples: a warning value state; lifecycle contexts like critical, reduced, borderline, or low stock levels

Chart Token	Morning Horizon
sapChart_Sequence_Critical_Plus3		#ffb881
sapChart_Sequence_Critical_Plus3_TextColor		#000000
sapChart_Sequence_Critical_Plus2		#ff933f
sapChart_Sequence_Critical_Plus2_TextColor		#000000
sapChart_Sequence_Critical_Plus1		#ff760c
sapChart_Sequence_Critical_Plus1_TextColor		#000000
sapChart_Sequence_Critical		#e26300
sapChart_Sequence_Critical_TextColor		#000000
sapChart_Sequence_Critical_Minus1		#c35600
sapChart_Sequence_Critical_Minus1_TextColor		#ffffff
sapChart_Sequence_Critical_Minus2		#aa4a00
sapChart_Sequence_Critical_Minus2_TextColor		#ffffff
sapChart_Sequence_Critical_Minus3		#903f00
sapChart_Sequence_Critical_Minus3_TextColor		#ffffff
sapChart_Sequence_Critical_Minus4		#6d3000
sapChart_Sequence_Critical_Minus4_TextColor		#ffffff
sapChart_Sequence_Critical_Minus5		#492000
sapChart_Sequence_Critical_Minus5_TextColor		#ffffff

Chart Sequence Good

Context examples: a successful or good value state; lifecycle contexts like positive, enhanced, healthy, or full stock levels

Chart Token	Morning Horizon
sapChart_Sequence_Good_Plus3		#88d79f
sapChart_Sequence_Good_Plus3_TextColor		#000000
sapChart_Sequence_Good_Plus2		#56c776
sapChart_Sequence_Good_Plus2_TextColor		#000000
sapChart_Sequence_Good_Plus1		#3ab05c
sapChart_Sequence_Good_Plus1_TextColor		#000000
sapChart_Sequence_Good		#30914c
sapChart_Sequence_Good_TextColor		#000000
sapChart_Sequence_Good_Minus1		#287a40
sapChart_Sequence_Good_Minus1_TextColor		#ffffff
sapChart_Sequence_Good_Minus2		#226736
sapChart_Sequence_Good_Minus2_TextColor		#ffffff
sapChart_Sequence_Good_Minus3		#1c542c
sapChart_Sequence_Good_Minus3_TextColor		#ffffff
sapChart_Sequence_Good_Minus4		#13391e
sapChart_Sequence_Good_Minus4_TextColor		#ffffff
sapChart_Sequence_Good_Minus5		#0a1e10
sapChart_Sequence_Good_Minus5_TextColor		#ffffff

Chart Sequence Neutral

Context examples: a null value state; lifecycle contexts like neutral, normal, regular, or medium stock levels.

Chart Token	Morning Horizon
sapChart_Sequence_Neutral_Plus3		#edf0f3
sapChart_Sequence_Neutral_Plus3_TextColor		#000000
sapChart_Sequence_Neutral_Plus2		#c2ccd7
sapChart_Sequence_Neutral_Plus2_TextColor		#000000
sapChart_Sequence_Neutral_Plus1		#9aabbc
sapChart_Sequence_Neutral_Plus1_TextColor		#000000
sapChart_Sequence_Neutral		#758ca4
sapChart_Sequence_Neutral_TextColor		#000000
sapChart_Sequence_Neutral_Minus1		#5b728b
sapChart_Sequence_Neutral_Minus1_TextColor		#ffffff
sapChart_Sequence_Neutral_Minus2		#495e74
sapChart_Sequence_Neutral_Minus2_TextColor		#ffffff
sapChart_Sequence_Neutral_Minus3		#364a5f
sapChart_Sequence_Neutral_Minus3_TextColor		#ffffff
sapChart_Sequence_Neutral_Minus4		#233649
sapChart_Sequence_Neutral_Minus4_TextColor		#ffffff
sapChart_Sequence_Neutral_Minus5		#1a2633
sapChart_Sequence_Neutral_Minus5_TextColor		#ffffff

Visual Accessibility

Enhancing Perceivable Contrast in Charts

The base set of chart colors has been tested for several color blindness types but can not cover all color blindness types.

Each color is defined with theming variables (tokens), which allow you to customize the color values using theming tools.

The extended chart sequence colors each have a corresponding text color and also a text shadow (halo) style that ensures sufficient text-to-background contrast. Additionally, built-in logic allows you to customize the chart tokens using theming tools. These provide an automatic switch between light and dark text and text shadow colors to enhance legibility.

All of the text shadow styles for each set of sequence text colors are provided as part of the SAP Theming Base Content repository.

Guidelines

Where possible, use a reduced set of chart color values to avoid information overload.
We strongly recommend providing additional means of interpreting chart values visually, such as labeling, tooltips, and patterns.

Example:

Chart Sequence Neutral color token:
sapChart_Sequence_Neutral: #758ca4
Non-text contrast to UI background (sapBackgroundColor): 3:1;

Text color token:
sapChart_Sequence_Neutral_TextColor: #000000;
Text contrast to neutral chart color (sapChart_Sequence_Neutral) color: 3:1;

Text shadow style token:
sapChart_Sequence_Neutral_TextShadow: 0 0 .125rem #fff;
A text shadow (halo) may be used to enhance text legibility.

Non-Text Contrast using Borders

Each set of sequence colors also has one border color that will ensure the correct contrast.

Border styles for each set of sequence colors are provided as part of the SAP Theming Base Content repository.

Guidelines

To ensure sufficient perceivable contrast for non-text elements, we recommend applying borders to any chart sequential values that fall below a 3:1 contrast measurement against the chart or user interface background.
The border must also have a 3:1 contrast against any chart interaction or highlight border colors.
It is also recommended that interaction borders differ in size as well as contrast.

Example:

Chart Sequence 1 border color token:
sapChart_Sequence_1_BorderColor: #3278BE
Non-text contrast to UI background (sapBackgroundColor): 4.2:1;
Non-text contrast to chart Interaction color (sapChart_Data_InteractiveColor): 4.5:1;

Chart color contrast measurements

Regular
Interactive
Chart border to UI/chart background: More than 3:1
Chart border color (Sequence_1) to interactive border color: More than 3:1

Text shadow (halo) measurement

Dark text measured against light halo
Light text measured against dark halo

The dark and light values for the text shadow ensure that text is always legible and never blurry.

Usage

Use the object display components if:

You need to display the semantic status of an object: negative, critical, positive, or neutral. Use the object status for this.
You want to display the key number of an object. In this case, use the object number and keep the default emphasized setting.
You need to display one or more numeric attributes of an object (for example, for objects you want to compare). Use the object number for this.
You want to indicate the key identifier of the object. Use the object identifier for this.
You want to display the technical state of an object (draft, unsaved changes, locked, favorite, flagged). Use the object marker for this, unless you want to display the status of the object in the business life cycle. In the latter case, consider using the object status instead.
You need to show that the current object instance is locked by another user. Use the object marker for this.

Do not use the object display components if:

You want to display system messages.
They are for decoration purposes only.

Responsiveness

The object status wraps if it is longer than the available screen width.
The object identifier text wraps if the size of the screen becomes too small to display the entire text on one line.
The object number does not wrap or truncate. For large numbers, use appropriate formatting.
The object marker does not wrap or truncate. It comes with different display options: IconAndText, IconOnly, and Text. On size S, the display option IconAndText displays only the icon. The other options are displayed as normal.

For more information about the responsive behavior of text in general, see Wrapping and Truncating Text.

From top to bottom: Wrapping examples for the object status, object identifier, formatted object number, and two versions of the object marker

Components

Object Status

The object status is a short text that represents the semantic status of an object.

It consists of the following:

A semantically colored text indicating its status (property: text). We recommend using this semantically colored text-only option on its own. Check out the How to Use Semantic Colors / Industry-Specific Colors article for color options.
An optional icon (property: icon). If you use an icon, ensure it’s well understood in the context. You can also use the following icon set for your use case:
= positive/success
= critical/warning
= negative/error
Note that there is no generic icon for “neutral” across industries. If you have a neutral object status, use the text-only version, or a blank icon. Only use an icon to denote “neutral” in the app-specific business context in exceptional cases.

Text-only object status and icon with text object status

An optional inverted visualization. Use the inverted object status if the information is crucial for the user’s actions and needs to stand out visually (for example, in table list items).
An optional link (property: active). If the object status is used as a link, a hover effect is shown on non-touch devices. Use this feature if the user needs additional information about the status (for example, in a popover). Note that if you use the object status as a combination of icon and text, there is no hover effect for the icon.

Inverted object status (left) and object status in hover state (right)

An optional larger font (CSS class: sapMObjectStatusLarge). Use this feature if the object status is important in the business context and needs to stand out visually in the page header (for example, key value facets in an object page).

Larger object status in the header facet for an object page

Guidelines

- Ensure that the context for the object status is properly described. The semantic meaning must also be understandable for color-blind people. Use the object status in combination with a label, icon, unit, or attribute to make the value state clear.
- In rare cases, an object can have two statuses at the same time. In this case, use the inverted text-only version for the most important status, and the normal text-only version (with an optional icon) for the less important status.
- If you use the object status in a table, follow the corresponding sorting guidelines.
- To prevent the text being read as a link, don’t use the blue “information state” for the object status.
- If the object status is interactive, add sufficient spacing to ensure that the area occupied by the object status on the screen is at least 24 x 24 px. This area must not overlap or intersect with any other components. The minimum target size is required to comply with the WCAG 2.2 accessibility standard.

Object Identifier

The object identifier is a short text that represents the key identifier of an object.

It has the following characteristics:

A title text (property: title)
An optional link (property: titleActive). In this case, the event can open the quick view of the object or a popover for example.
An optional additional descriptive text (property: text)

Guidelines

The object identifier should be easily readable (preferably the display text and not the ID).
If the object’s ID is necessary to distinguish between items that use the same title, it should appear as descriptive text below the title (property: text).
If the object identifier is interactive, add sufficient spacing to ensure that the area occupied by the object identifier on the screen is at least 24 x 24 px. This area must not overlap or intersect with any other components. The minimum target size is required to comply with the WCAG 2.2 accessibility standard.

Normal object identifier, object identifier with link, and object identifier with descriptive text

Object Number

The object number is a short text that represents the numeric (key) attribute of an object and its unit.

It consists of the following:

A colored text (property: number) based on the semantic color palette. Check out the How to Use Semantic Colors / Industry-Specific Colors article for more details.
An optional unit (property: unit).

Emphasized and non-emphasized object numbers

An emphasized text which you can set to non-emphasized when you use it in the content area (property: emphasized).

Object number used as a semantic attribute (weight)

An optional inverted visualization of a crucial number, which needs to visually stand out and attract the user’s attention (property: inverted). Use this visualization sparely and not more than two of them on one page.

Inverted object numbers and normal object number in comparison

An optional larger font (CSS class: sapMObjectNumberLarge). Use this feature if the object number is important in the business context and needs to stand out visually in the page header (for example, key value facets in an object page). Once the large font is applied, the object number can no longer be emphasized.

Guidelines

Don’t use a semantic color alone to indicate a value state. Ensure that the context for the object number is properly described. The semantic meaning must also be understandable for color-blind people. Use the object number in combination with a label, icon, unit, or attribute to make the specific context of the value state in your application clear.
The object number can also be used to visualize other semantic numeric attributes. In this case, they are not emphasized unless they are the key attribute, such as a sum.
Emphasize the object number if it is used as a line item status in a table.

Emphasized and non-emphasized object numbers in the header facet for an object page

Object Marker

The object marker indicates the technical status of an object and can be interactive. It is enabled for the dynamic page layout, the snapping header, the object page header, the upload set control, and the object list item. You can represent the technical status as an icon, with an icon and text, or as text only, depending on the screen size.

Currently, the following technical statuses can be visualized by the object marker:

Editing Status: Draft, Unsaved Changes, Locked. The editing status is part of the draft handling concept.
Favorite
Flag

Flag and Favorite are usually displayed as icons on all screen sizes. For more information, see Flag and Favorite.

An object can have multiple technical statuses at the same time. However, because the editing statuses are mutually exclusive, users will see a maximum of 3 technical statuses for an object: Flag, Favorite, and one Editing Status.

Developer Hint

The app developer is responsible for the technical statuses. Every technical status has a default visualization that can be changed by the app developer depending on the usage context. For details regarding draft handling, see How to Display the Editing Status in the Draft Handling article.

If the object marker is interactive, add sufficient spacing to ensure that the area occupied by the object marker on the screen is at least 24 x 24 px. This area must not overlap or intersect with any other components. The minimum target size is required to comply with the WCAG 2.2 accessibility standard.

Icons for draft, unsaved changes, locked, favorite, and flag (from left to right)

Editing status examples

Resources

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

Elements and Controls

How to Use Semantic Colors (guidelines)
Wrapping and Truncating Text (guidelines)
Draft Handling (guidelines)
Flag and Favorite (guidelines)
Responsive Table (guidelines)

Implementation

Object Status (SAPUI5 samples)
Object Status (SAPUI5 API reference)
Object Identifier (SAPUI5 samples)
Object Identifier (SAPUI5 API reference)
Object Number (SAPUI5 samples)
Object Number (SAPUI5 API reference)
Object Marker (SAPUI5 samples)
Object Marker (SAPUI5 API reference)

Filter Bar

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

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

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

When to Use

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

Do not use the filter bar:

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

Filter Bar Components

Expanded Filter Bar

The expanded filter bar consists of:

Views (optional)
Basic search field (optional)
Filter input controls
Go button (only for manual update mode)
Adapt Filters button

Expanded filter bar

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

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

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

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

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

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

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

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

Collapsed Filter Bar

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

Collapsed filter bar

It shows a summary of the filters currently applied:

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

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

“Adapt Filters” Dialog

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

Adapt Filters dialog - list view, hidden values

The Adapt Filters dialog consists of:

Select control and search
Show Values/Hide Values toggle
List or group view
Mandatory and optional filters
Footer bar buttons
Arrows to move the filter up and down
Active filter with assigned value

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

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

Searching and Displaying Filters in the Dialog

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

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

In the dialog, when a mandatory filter has:

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

In the dialog, users can display the filters:

With or without the filter values (2).

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

In the list or group view (3).

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

Displaying Filters in the Filter Bar

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

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

In the Adapt Filters footer bar (5):

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

Resetting Filters

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

Adapt Filters dialog - list view, values shown

Adapt Filters dialog - grouped view, hidden values

Adapt Filters dialog - grouped view, values shown

Filter Input Controls

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

For	Use
A predefined list for single or multiple selection	The select control or combo box control
Temporal information	The date picker or date range selector
Multi-input fields	Suggestions to help the user enter a valid value

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

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

Developer Hint

For development information, see Data Types for the smart filter bar.

For more information on the selection controls, see:

Behavior and Interaction

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

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

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

Responsiveness

The name of the view or title is always visible.

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

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

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

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

Examples

Top Tips

Filter Bar

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

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

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

Filter Input Controls

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

Preset Filter Values

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

Update Mode

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

Usage

Use the object display components if:

You need to display the semantic status of an object: negative, critical, positive, or neutral. Use the object status for this.
You want to display the key number of an object. In this case, use the object number and keep the default emphasized setting.
You need to display one or more numeric attributes of an object (for example, for objects you want to compare). Use the object number for this.
You want to indicate the key identifier of the object. Use the object identifier for this.
You want to display the technical state of an object (draft, unsaved changes, locked, favorite, flagged). Use the object marker for this, unless you want to display the status of the object in the business life cycle. In the latter case, consider using the object status instead.
You need to show that the current object instance is locked by another user. Use the object marker for this.

Do not use the object display components if:

You want to display system messages.
They are for decoration purposes only.

Responsiveness

The object status wraps if it is longer than the available screen width.
The object identifier text wraps if the size of the screen becomes too small to display the entire text on one line.
The object number does not wrap or truncate. For large numbers, use appropriate formatting.
The object marker does not wrap or truncate. It comes with different display options: IconAndText, IconOnly, and Text. On size S, the display option IconAndText displays only the icon. The other options are displayed as normal.

For more information about the responsive behavior of text in general, see Wrapping and Truncating Text.

From top to bottom: Wrapping examples for the object status, object identifier, formatted object number, and two versions of the object marker

Components

Object Status

The object status is a short text that represents the semantic status of an object.

It consists of the following:

A semantically colored text indicating its status (property: text). We recommend using this semantically colored text-only option on its own. Check out the How to Use Semantic Colors / Industry-Specific Colors article for color options.
An optional icon (property: icon). If you use an icon, ensure it’s well understood in the context. You can also use the following icon set for your use case:
= positive/success
= critical/warning
= negative/error
Note that there is no generic icon for “neutral” across industries. If you have a neutral object status, use the text-only version, or a blank icon. Only use an icon to denote “neutral” in the app-specific business context in exceptional cases.

Text-only object status and icon with text object status

An optional inverted visualization. Use the inverted object status if the information is crucial for the user’s actions and needs to stand out visually (for example, in table list items).
An optional link (property: active). If the object status is used as a link, a hover effect is shown on non-touch devices. Use this feature if the user needs additional information about the status (for example, in a popover). Note that if you use the object status as a combination of icon and text, there is no hover effect for the icon.

Inverted object status (left) and object status in hover state (right)

An optional larger font (CSS class: sapMObjectStatusLarge). Use this feature if the object status is important in the business context and needs to stand out visually in the page header (for example, key value facets in an object page).

Larger object status in the header facet for an object page

Guidelines

- Ensure that the context for the object status is properly described. The semantic meaning must also be understandable for color-blind people. Use the object status in combination with a label, icon, unit, or attribute to make the value state clear.
- In rare cases, an object can have two statuses at the same time. In this case, use the inverted text-only version for the most important status, and the normal text-only version (with an optional icon) for the less important status.
- If you use the object status in a table, follow the corresponding sorting guidelines.
- To prevent the text being read as a link, don’t use the blue “information state” for the object status.
- If the object status is interactive, add sufficient spacing to ensure that the area occupied by the object status on the screen is at least 24 x 24 px. This area must not overlap or intersect with any other components. The minimum target size is required to comply with the WCAG 2.2 accessibility standard.

Object Identifier

The object identifier is a short text that represents the key identifier of an object.

It has the following characteristics:

A title text (property: title)
An optional link (property: titleActive). In this case, the event can open the quick view of the object or a popover for example.
An optional additional descriptive text (property: text)

Guidelines

The object identifier should be easily readable (preferably the display text and not the ID).
If the object’s ID is necessary to distinguish between items that use the same title, it should appear as descriptive text below the title (property: text).
If the object identifier is interactive, add sufficient spacing to ensure that the area occupied by the object identifier on the screen is at least 24 x 24 px. This area must not overlap or intersect with any other components. The minimum target size is required to comply with the WCAG 2.2 accessibility standard.

Normal object identifier, object identifier with link, and object identifier with descriptive text

Object Number

The object number is a short text that represents the numeric (key) attribute of an object and its unit.

It consists of the following:

A colored text (property: number) based on the semantic color palette. Check out the How to Use Semantic Colors / Industry-Specific Colors article for more details.
An optional unit (property: unit).

Emphasized and non-emphasized object numbers

An emphasized text which you can set to non-emphasized when you use it in the content area (property: emphasized).

Object number used as a semantic attribute (weight)

An optional inverted visualization of a crucial number, which needs to visually stand out and attract the user’s attention (property: inverted). Use this visualization sparely and not more than two of them on one page.

Inverted object numbers and normal object number in comparison

An optional larger font (CSS class: sapMObjectNumberLarge). Use this feature if the object number is important in the business context and needs to stand out visually in the page header (for example, key value facets in an object page). Once the large font is applied, the object number can no longer be emphasized.

Guidelines

Ensure that the context for the object number is properly described. The semantic meaning must also be understandable for color-blind people. Use the object number in combination with a label, icon, unit, or attribute to make the value state clear.
The object number can also be used to visualize other semantic numeric attributes. In this case, they are not emphasized unless they are the key attribute, such as a sum.
Emphasize the object number if it is used as a line item status in a table.

Emphasized and non-emphasized object numbers in the header facet for an object page

Object Marker

The object marker indicates the technical status of an object and can be interactive. It is enabled for the dynamic page layout, the snapping header, the object page header, the upload set control, and the object list item. You can represent the technical status as an icon, with an icon and text, or as text only, depending on the screen size.

Currently, the following technical statuses can be visualized by the object marker:

Editing Status: Draft, Unsaved Changes, Locked. The editing status is part of the draft handling concept.
Favorite
Flag

Flag and Favorite are usually displayed as icons on all screen sizes. For more information, see Flag and Favorite.

An object can have multiple technical statuses at the same time. However, because the editing statuses are mutually exclusive, users will see a maximum of 3 technical statuses for an object: Flag, Favorite, and one Editing Status.

Developer Hint

The app developer is responsible for the technical statuses. Every technical status has a default visualization that can be changed by the app developer depending on the usage context. For details regarding draft handling, see How to Display the Editing Status in the Draft Handling article.

If the object marker is interactive, add sufficient spacing to ensure that the area occupied by the object marker on the screen is at least 24 x 24 px. This area must not overlap or intersect with any other components. The minimum target size is required to comply with the WCAG 2.2 accessibility standard.

Icons for draft, unsaved changes, locked, favorite, and flag (from left to right)

Editing status examples

Resources

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

Elements and Controls

How to Use Semantic Colors (guidelines)
Wrapping and Truncating Text (guidelines)
Draft Handling (guidelines)
Flag and Favorite (guidelines)
Responsive Table (guidelines)

Implementation

Object Status (SAPUI5 samples)
Object Status (SAPUI5 API reference)
Object Identifier (SAPUI5 samples)
Object Identifier (SAPUI5 API reference)
Object Number (SAPUI5 samples)
Object Number (SAPUI5 API reference)
Object Marker (SAPUI5 samples)
Object Marker (SAPUI5 API reference)

Object Display Components

There are four types of object display component: object status, object identifier, object number, and object marker. Each one is connected to an object and displays a certain type of information (status, identifier, number, marker).

Object status: a short text that represents the semantic status of an object
Object identifier: a short text that represents the key identifier of an object
Object number: a short text that represents the numeric (key) attribute of an object and its unit
Object marker: indicates the technical status of an object

From top to bottom: Examples for the object status, object identifier, object number, and object marker

Usage

Use the object display components if:

You need to display the semantic status of an object: negative, critical, positive, or neutral. Use the object status for this.
You want to display the key number of an object. In this case, use the object number and keep the default emphasized setting.
You need to display one or more numeric attributes of an object (for example, for objects you want to compare). Use the object number for this.
You want to indicate the key identifier of the object. Use the object identifier for this.
You want to display the technical state of an object (draft, unsaved changes, locked, favorite, flagged). Use the object marker for this, unless you want to display the status of the object in the business life cycle. In the latter case, consider using the object status instead.
You need to show that the current object instance is locked by another user. Use the object marker for this.

Do not use the object display components if:

You want to display system messages.
They are for decoration purposes only.

Responsiveness

The object status wraps if it is longer than the available screen width.
The object identifier text wraps if the size of the screen becomes too small to display the entire text on one line.
The object number does not wrap or truncate. For large numbers, use appropriate formatting.
The object marker does not wrap or truncate. It comes with different display options: IconAndText, IconOnly, and Text. On size S, the display option IconAndText displays only the icon. The other options are displayed as normal.

For more information about the responsive behavior of text in general, see Wrapping and Truncating Text.

From top to bottom: Wrapping examples for the object status, object identifier, formatted object number, and two versions of the object marker

Components

Object Status

The object status is a short text that represents the semantic status of an object.

It consists of the following:

A semantically colored text indicating its status (property: text). We recommend using this semantically colored text-only option on its own. Check out the How to Use Semantic Colors / Industry-Specific Colors article for color options.
An optional icon (property: icon). If you use an icon, ensure it’s well understood in the context. You can also use the following icon set for your use case:
= positive/success
= critical/warning
= negative/error
Note that there is no generic icon for “neutral” across industries. If you have a neutral object status, use the text-only version, or a blank icon. Only use an icon to denote “neutral” in the app-specific business context in exceptional cases.

Text-only object status and icon with text object status

An optional inverted visualization. Use the inverted object status if the information is crucial for the user’s actions and needs to stand out visually (for example, in table list items).
An optional link (property: active). If the object status is used as a link, a hover effect is shown on non-touch devices. Use this feature if the user needs additional information about the status (for example, in a popover). Note that if you use the object status as a combination of icon and text, there is no hover effect for the icon.

Inverted object status (left) and object status in hover state (right)

An optional larger font (CSS class: sapMObjectStatusLarge). Use this feature if the object status is important in the business context and needs to stand out visually in the page header (for example, key value facets in an object page).

Larger object status in the header facet for an object page

Guidelines

- Ensure that the context for the object status is properly described. The semantic meaning must also be understandable for color-blind people. Use the object status in combination with a label, icon, unit, or attribute to make the value state clear.
- In rare cases, an object can have two statuses at the same time. In this case, use the inverted text-only version for the most important status, and the normal text-only version (with an optional icon) for the less important status.
- If you use the object status in a table, follow the corresponding sorting guidelines.
- To prevent the text being read as a link, don’t use the blue “information state” for the object status.

Object Identifier

The object identifier is a short text that represents the key identifier of an object.

It has the following characteristics:

A title text (property: title)
An optional link (property: titleActive). In this case, the event can open the quick view of the object or a popover for example.
An optional additional descriptive text (property: text)

Guidelines

The object identifier should be easily readable (preferably the display text and not the ID).
If the object’s ID is necessary to distinguish between items that use the same title, it should appear as descriptive text below the title (property: text).

Normal object identifier, object identifier with link, and object identifier with descriptive text

Object Number

The object number is a short text that represents the numeric (key) attribute of an object and its unit.

It consists of the following:

A colored text (property: number) based on the semantic color palette. Check out the How to Use Semantic Colors / Industry-Specific Colors article for more details.
An optional unit (property: unit).

Emphasized and non-emphasized object numbers

An emphasized text which you can set to non-emphasized when you use it in the content area (property: emphasized).

Object number used as a semantic attribute (weight)

An optional inverted visualization of a crucial number, which needs to visually stand out and attract the user’s attention (property: inverted). Use this visualization sparely and not more than two of them on one page.

Inverted object numbers and normal object number in comparison

An optional larger font (CSS class: sapMObjectNumberLarge). Use this feature if the object number is important in the business context and needs to stand out visually in the page header (for example, key value facets in an object page). Once the large font is applied, the object number can no longer be emphasized.

Guidelines

Ensure that the context for the object number is properly described. The semantic meaning must also be understandable for color-blind people. Use the object number in combination with a label, icon, unit, or attribute to make the value state clear.
The object number can also be used to visualize other semantic numeric attributes. In this case, they are not emphasized unless they are the key attribute, such as a sum.
Emphasize the object number if it is used as a line item status in a table.

Emphasized and non-emphasized object numbers in the header facet for an object page

Object Marker

The object marker indicates the technical status of an object and can be interactive. It is enabled for the dynamic page layout, the snapping header, the object page header, the upload set control, and the object list item. You can represent the technical status as an icon, with an icon and text, or as text only, depending on the screen size.

Currently, the following technical statuses can be visualized by the object marker:

Editing Status: Draft, Unsaved Changes, Locked. The editing status is part of the draft handling concept.
Favorite
Flag

Flag and Favorite are usually displayed as icons on all screen sizes. For more information, see Flag and Favorite.

An object can have multiple technical statuses at the same time. However, because the editing statuses are mutually exclusive, users will see a maximum of 3 technical statuses for an object: Flag, Favorite, and one Editing Status.

Developer Hint

The app developer is responsible for the technical statuses. Every technical status has a default visualization that can be changed by the app developer depending on the usage context. For details regarding draft handling, see How to Display the Editing Status in the Draft Handling article.

Icons for draft, unsaved changes, locked, favorite, and flag (from left to right)

Editing status examples

Resources

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

Elements and Controls

How to Use Semantic Colors (guidelines)
Wrapping and Truncating Text (guidelines)
Draft Handling (guidelines)
Flag and Favorite (guidelines)
Responsive Table (guidelines)

Implementation

Object Status (SAPUI5 samples)
Object Status (SAPUI5 API reference)
Object Identifier (SAPUI5 samples)
Object Identifier (SAPUI5 API reference)
Object Number (SAPUI5 samples)
Object Number (SAPUI5 API reference)
Object Marker (SAPUI5 samples)
Object Marker (SAPUI5 API reference)

Tree

Within SAP Fiori, we distinguish between tree tables and trees. Both usually allow the user to display and work with a hierarchical set of items. While tree tables are usually used for more complex data, trees are generally used for rather basic data. Trees are mostly used in the main list for a list-detail scenario using the flexible column layout and in popovers or dialogs. In certain use cases, they can also be used in the dynamic page layout.

In the case of tree tables and trees, items that contain additional items are called nodes, while items that do not contain any other items are called leaves. If available, a single topmost node is called a root node. Apart from the hierarchical structure of its nodes and leaves, a tree is quite similar to a list.

Usage

Use the tree if:

You need to display the key identifier of hierarchically structured items (for example in the first column of the flexible column layout).
Selecting one or more items out of a set of hierarchically structured items is a main use case.
The hierarchy has a restricted number of levels (up to about 12, depending on the content) and items (around 200).
You want to have only one implementation for all devices.

Do not use the tree if:

The main use case is to select one item from a very small number of non-hierarchical items, without viewing additional details. In this case, a select or combo box might be more appropriate.
Items are not structured hierarchically. Use a list instead.
The hierarchy turns out to have only two levels. In this case, use a grouped list.
The hierarchy turns out to be just a categorization based on several details of the item. In this case, an analytical table provides multi-level grouping. Note that the analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
You need to display very deep hierarchies with additional data per item. In this case, use a tree table. Note that the tree table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
The structure contains more than around 200 items. In this case, use the tree table. It is optimized for large item sets and provides better performance. Note that the tree table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
You need an overview of a large amount of data. In this case, use a chart.

Check out the table overview to decide which SAP Fiori table is most suitable for your needs.

Responsiveness

The tree is like a list containing hierarchical data. It acts as a container for items, with the possibility to expand and collapse nodes. When reducing the width, item texts wrap to ensure that the tree adapts to the new size.

In addition, the tree changes the indentation per level dynamically when the user expands a node, based on number of levels currently showing.

Tree displaying 2 levels

Tree displaying 3 levels

Tree displaying 4 levels

Layout

The title bar (optional) contains the title of the tree. In addition, an item counter and toolbar items can be placed on the title bar.
The collection of hierarchical items occupies the main part of the tree.

Schematic visualization of the tree

Components

The title bar consists of a toolbar. The toolbar can contain a title, an item count, and other toolbar items such as actions or view settings, for example.

The standard tree item consists of:

A highlight indicator (optional)
An expand/collapse button for nodes
A selector in form of a checkbox or a radio button (optional)
An icon (optional)
A text
A counter (optional)
Additional buttons with actions such as Edit, Navigate, or Delete (optional)

If additional controls are needed, use a custom tree item. The custom tree item allows you to use any combination of controls inside the tree.

Standard tree item

Behavior and Interaction (incl. Gestures)

Tree Level

Scrolling

The height of the tree is defined by the number of items it contains. It does not have its own scroll container, but is scrolled together with the app.

Same tree, with different expand state

When the user scrolls, the title and the filter infobar can stick to the top of the surrounding layout container (sap.m.Tree, property: sticky).

Information

The “sticky” feature comes with some limitations:

It is not available on all browsers. In non-supporting browsers, the corresponding areas are not fixed on top of the surrounding layout container while scrolling.
Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the table is placed within the object page.
If focus is set to a sticky area, the tree is automatically scrolled to top.

Sticky title

Selection Modes

A tree can have one of the following selection modes (sap.m.Tree / sap.m.ListBase, property: mode):

None: Items cannot be selected (sap.m.ListMode.None).
Beware: Items can, nevertheless, use the sap.m.ListType “navigation” which allows click-handling on specific items. This should only be used when the click triggers a navigation to a corresponding item details page.

Tree without selectable items

Single select master: One item of the tree can be selected. To select an item, click anywhere on the item. Single select master does not add any visual indication to the tree and therefore cannot be differentiated from trees without selection if no item is selected. Therefore, always keep one item selected. For single selection, this is the preferred mode. (sap.m.ListMode.SingleSelectMaster)

Single selection: Only one item is selected.

Single select left: One item of the tree can be selected. For this, the tree provides radio buttons on the left side of each line item. Use this selection mode only if clicking on the item triggers something else, such as a navigation. Ideally, always keep one item selected, even in initial state (sap.m.ListMode.SingleSelectLeft).

Single selection with radio buttons. Use only if row clicks are used for something else, for example navigation.

Multiple selection: Allows the selection of one or more items. For this, the tree provides checkboxes on the left side of each line item. Each item is selected independently of the others. The Shift key can be used to select a range. Users can (de)select all items using Ctrl+A. Select All should (de)select all items that the user can reach by scrolling. (sap.m.ListMode.MultiSelect).

Developer Hint

In multiple selection mode, users can (de)select all items using the shortcut Ctrl+A. This only affects items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded (for example, items added via lazy loading with growingScrollToLoad). This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

Also note that Ctrl+A only (de)selects items within expanded nodes.

To process all items, listen to the selectionChange event and to its flag selectAll. This indicates whether Ctrl+A was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

Guidelines

Never disable the selection checkbox. If an action can’t be performed on a specific item, inform the user after the corresponding action has been triggered. For more information, see Enabling/Disabling Actions.
For single-selection list-detail scenarios within the flexible column layout, use the mode “single select master”. Do not show an additional “navigated” indicator.
Avoid the mode “single select left”. It removes the possibility of clicking somewhere on the item to select it. Use it only if it is really necessary to have two different click areas; a small one for a selection, and the rest of the item for something else.
If selecting / deselecting all items is important for your app, add a button Select All to the toolbar. Change the button text to Deselect All if all items are selected.

Multiple selection

Deleting

To delete single items, use the tree in “delete” mode (sap.m.Tree / sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This adds a Delete button to each item. Clicking this button triggers the deletion of the corresponding item. Do not use this mode if deleting multiple items at once is the preferred use case. Delete is a mode of the tree and therefore cannot be used together with single selection or multi selection.

Tree in 'delete' mode

Line Item Level

Expandable and Collapsible Nodes

An Expand/Collapse button is provided automatically for each node.

Expand/collapse button

Highlight an Item

To highlight an item, use the “highlight” indicator (sap.m.TreeItemBase, properties: highlight).

Highlighted item

Navigating

To allow navigation from an item, set type to “navigation” within the corresponding item (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This will create an indicator at the end of the line (“>”) and the entire item will become selectable. Clicking the line triggers the navigation event. However, clicking a selectable area or an expandable/collapse node does not. Use the navigation event to navigate to a new page containing item details.
If no navigation is possible, set type to “inactive”.
Navigation is an item type and therefore cannot be used together with “edit” or in combination with click events for the entire item (“active”).

Tree items with navigation indicator

Navigation indicators can be set per item

Indicate Navigated Item

When multi-selection 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 only (multi-selection tree with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.TreeItemBase, property: navigated).

Navigated item

Editing Items

To allow the user to edit an item, set type to “detail” within the corresponding item (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive). This will create an edit button at the end of the line. Clicking the button triggers the edit event. Use this event to either open a dialog or a details page where the item can be edited.
Edit is an item type and therefore cannot be used together with “navigation” or in combination with click events for the entire item (“active”).

Edit button

Clicking an Item

Items as a whole can be clickable. An event is fired by clicking on the item (anywhere except when triggering a selection or when expanding/collapsing a node). Apps can react to the event, such as by opening a dialog (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Active or sap.m.ListType.DetailAndActive).
Active elements do not have a visual indication and therefore cannot be differentiated from non-active elements.
“Active” is an item type and therefore cannot be used together with “navigation” or “edit”. In addition, “active” uses the entire item as a clickable area and thus cannot be used together with the “single select master” mode.

Active items

Context Menu

The context menu can be triggered for the tree or per item.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or Shift+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a tree is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Tree - Context menu

Drag and Drop

One or several items can be repositioned within a tree or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop

Whole item as drop target

Guidelines

Tree vs. List

Trees are more complex than lists due to their hierarchical view. Users tend to have more problems finding items in hierarchical views than in flat lists, except where the hierarchical view is natural. By natural we mean that every child node should be part of only one parent, and this relationship between the child and parent is clear and well known.

Example of an acceptable use of trees

Do

A clear parent-child relationship

Broad vs. Deep Hierarchies

When you use trees, you should choose broad hierarchies over deep hierarchies. Deep hierarchies make finding items more complicated. So try to reduce hierarchical levels where possible, especially if the hierarchy is not natural. Ideally, a tree should have a maximum of four levels, the first two of which should contain the most important items.

Don't

Avoid unnecessary depth in the hierarchy

Do

Favor breadth over depth in a hierarchy

You can use the following methods to reduce hierarchy levels:

Avoid a single root node. It is usually not needed.
Container nodes at the top level can usually be replaced by tabs or value pickers.
Eliminate unnecessary mid-level containers, for example, by combining redundant ones.
Exercise care when using a tree due to its overall complexity. The hierarchical structure of the data does not necessarily mean that a tree control is required.

Acceptable: repeat entries to optimize finding items

Design Concepts

The tree can be used to display hierarchical data. Unfortunately, trees convey an immediate feeling of complexity. Ideally, show trees only if there is no other option. You should instead try the following:

Flatten the data. A list is still complex, but less so than a tree. A combo box might also fit in some use cases.
When only two levels are needed, a grouped list control can be used. This works well, where group nodes are used for categorizing their children and where the group nodes themselves do not need to be selectable.
Break down the data into manageable chunks. Allow the user to navigate or drill down between them.
Use charts with drilldown functionality until the amount of data is more manageable.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the tree. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning

The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

The number of rows in the table
The number of displayed columns
The complexity of the cell content (for example, simple text vs. complex charts)
Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
The browser being used

Title

Use a title only if the title of the tree is not indicated in the surrounding area. If needed, implement the title text by adding a title to a toolbar. Place the toolbar above the tree.

Do not use a title if it simply repeats text that is already above the tree. For example:

A Beverages tree is the only control on a tab labeled Beverages.
A section or subsection on an object page contains only one tree.

Use a title if you need the item count, toolbar, or variant management. To avoid repeating text, feel free to use generic text as a title, such as Items.
Exception: If the surrounding area contains the title, and both the item count and toolbar can be added to the surrounding area, no additional title is needed.
Example: An object page (sub-)section contains only one tree. In this case, add the item count and the table toolbar to the (sub-)section header.

If you use a title, be sure to include the following:

A title text for the tree.
An (optional) item count using the following format: Title (Number of Items). For example, Items (17). Depending on the use case, either count all items or only leaves (for example, if nodes are mainly used for categorization).

Remove the item count in the title if there are zero items.

If possible, keep the toolbar sticky (sap.m.Tree, property: sticky).

Developer Hint

Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the tree.

If you don’t use a title (for example, to avoid repetition), make sure that the tree is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

Title

Title with item count

Loading Data

To indicate that the tree is currently loading items, use the busy state (sap.m.Tree, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Tree in busy state while loading data

Initial Display

Think of the initial expandable/collapsible state of a tree. If your structure contains many items on the root level, it might make sense to collapse the whole tree in its initial state.

In contrast, if the most important items are displayed on a deeper level (if, for example, the parent nodes are simply a kind of categorization), the tree should be expanded up to the first level where the most important items immediately appear.

Errors and Warnings

To indicate that the tree contains items with errors or warnings, show a message strip above the tree. On the message strip, provide information about errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

To indicate an error in a single row, see Item States below.

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

Developer Hint

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

Tree containing errors

Content

Content Formatting

To display object names with an ID, show the ID in parentheses after the corresponding object name.

Place the ID in brackets after the corresponding object name

Try not to display an empty tree. If there is no way around this, provide instructions on how to fill the tree with data (sap.m.Tree / sap.m.ListBase, properties: showNoData, noDataText).

Examples:

If a tree is initially empty, provide at least a basic text:
No items available.
Overwrite this whenever a hint can be provided on how to fill the tree with data.
If a tree is used together with a filter bar (as in the list report), and is initially empty, use the following text:
No filters set. To start, enter your search and filter settings and run the search.
If a tree is used together with a filter bar and the filter does not return results, use the following text:
No items found. Check the search and filter settings.

Adapt the texts above if:

The text is not precise enough for your use case (for example, no search is offered, only the search is offered).
You are using the live search (no Go button in the filter bar). In this case, leave out “run the search”.
The standard text is misleading (for example, if the data is filled based on a list-detail pattern instead of search and filter settings).

Provide meaningful instructions within an empty tree

Highlighting Items

To show that an item needs attention, you can display a highlight indicator in front of the item. The highlight indicator can be used to indicate:

A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted items

Item States

To show that an item has been modified, for example within the global edit flow, add the string (Modified) to the text of the item.

A modified item

To show that a modified item contains an error, for example within the global edit flow, add the string (Contains errors) to the text of the item and highlight the row accordingly. A row with errors should be highlighted in all use cases – for example when the field is visible in the row in edit mode.

A modified item with an error

To show that an item is locked, add the string (Locked by [name]) to the text of the item.

A locked item

To show that an item is in a draft state, add the string (Draft) to the text of the item.

Item in draft state

Show only one state at any one time.

Actions

To trigger actions on items, show the actions on a toolbar above the tree. Do not offer action triggering on multiple items if the tree is expected to have fewer than 10 items in most cases.
The following actions on single items must always be in-line:

Delete: Use “Delete” mode (sap.m.Tree / sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This places a Delete button at the end of each item.

Items with 'Delete' button

Navigation: Use the “Navigation” item type (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This places a navigation indicator at the end of the corresponding items. Use this to navigate to a new page containing item details.

Items with navigation indicator

Edit: Use the “Detail” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail). This places an Edit icon at the end of the corresponding items.

Edit button

From these three actions (delete, navigation, and edit), you can combine delete and edit, or delete and navigation. Edit and navigation cannot be combined.

To trigger actions that are independent of the selection, show the actions on a toolbar above the tree. For example: Add, Collapse All, Expand All, …

To trigger a default action on the entire item, use the “Active” or “DetailAndActive” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Active). Active items trigger an event when clicked, which can be handled by apps, for example, to open a dialog. Selection and expanding/collapsing a node does not trigger the event, but are handled by the tree. Do not use this for navigation, to switch the line item to an edit state, or to delete the item.
Active can be combined with edit and delete, but not with navigation. Do not combine active with single selection master.

Add Items

For adding items, place an Add or Create text button on the tree toolbar.

Use Create if the button adds a brand new item that doesn’t yet exist on the database.
Use Add if the item already exists and is merely added or assigned to the current object.

Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

Show new items as the first item of the tree or node:

If nothing is selected, add the new item to the root.
If a single node is selected, add the new item to the selected node.
If a single leaf is selected, add the new item as a child of this leaf. The original selected item becomes a node.

If your tree doesn’t support adding items to the root, selected node, or selected leaf, disable Create or Add for the corresponding levels.

Disable Create or Add if more than one item is selected.

There are three options for adding an item. In order of priority (most recommended first), these are:

Add the item inline. Create an empty, editable item as the first item of the selected node. Show the Save button on the tree toolbar. This option is recommended for simple scenarios where just a few input fields have to be filled.
Open a dialog for items where up to 8 input fields need to be filled. Save the new item at dialog level.
Navigate to a new page. This behavior should only be used for very complex scenarios that cannot be handled by a dialog (for example, creating complex objects). When the user presses Save in the footer toolbar of the create page, navigate back to the tree.

Depending on the flow, an item can be in one of three different states:

New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the corresponding node. Ignore current sort, filter, and grouping criteria to keep the item visible.
Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
- Inline creation: After Save was triggered on the tree toolbar or at page level.
- Create with dialog: A tree showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

In the context of draft handling, new items are not saved at tree level, but rather with the entire draft.

For more details, see the guidelines for managing objects (including subarticles).

Editing Items

To edit items, add an Edit button either in-line on the toolbar above the tree. Triggering the button either opens a dialog or navigates to an editable details page.

For mass editing:

Provide multiselection (sap.m.Tree/ sap.m.ListBase, property: mode, value: sap.m.ListMode.MultiSelect).
Provide an Edit button on the toolbar above the tree.
If several items are selected, triggering the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

For more details, see mass editing.

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

Drag and Drop

Warning

To comply with the new WCAG 2.2 standard, the control must offer an alternative to the drag and drop feature. See the visible alternatives described below.

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items. These are keyboard operable and available on all browsers.

Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within a tree, use the following options:

For dropping items as a child, use whole nodes as drop targets (sap.ui.core.dnd.DropPosition.On).
For dropping items on the same level, use the space between items as drop targets (sap.ui.core.dnd.DropPosition.Between).
If you want to allow users to drop items as a child or sibling, offer both drop targets (sap.ui.core.dnd.DropPosition.OnOrBetween).

This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Do not combine rearranging items within one level and sorting. If you really need to do so, make sure there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

Moving items from one node to another can be combined with sorting without any issues.

Drop targets in between items

Visible Alternatives to Drag and Drop

Depending on the functionality you need, use one or more of the following alternatives:

To move items up or down within a node:
Use the Move Up and Move Down buttons on the toolbar. These buttons move the selected items until the first selected item can’t be moved up or the last selected item can’t be moved down any further.
Depending on your tree, this can make sense for both leaves and nodes, only for leaves, or only for nodes. When moving a node, move the whole node and (if applicable) all its children up or down to the next position within the parent node.
Always make sure that when the user moves an item in one direction and then moves it back, the order is the same as it was before.
Do not combine the option to move items up and down with sorting.
To move items to another node:
Use Copy and Paste buttons on the toolbar.
Alternatively, offer a Move To button. Clicking Move To opens a dialog that shows all the nodes of the tree, but no leaves. Selecting an item in this dialog closes the dialog and moves the corresponding items to the selected node.
To change the level of an item:
In some trees, such as document structures, users can change the level of an item without affecting the level of parent or child items. In this case, use left and right arrow buttons ( ).

Filtering

What exactly needs to stay or be removed is highly dependent on the kind of structure and data your tree displays. For many trees, the following approach works well if you want to apply filters only to the leaves of a tree:

Remove all leaves that don’t fit the filter criteria
Remove empty nodes

If you also apply filters to nodes, keep the following in mind:

A node may or may not fit the filter criteria.
A node can contain items (nodes and/or leaves) that fit the filter criteria.

Because of this, the results might contain more nodes than those that are relevant for the filter criteria.

Information

The tree control itself has no influence on the filter result. It sends a filter request and displays whatever comes back. Make sure that the result set is meaningful.

Sorting

Before you start, ask yourself if sorting is meaningful in your tree. If so, decide on a meaningful default sort order.

If sorting is meaningful, is it meaningful on all levels? Or does the tree structure need to be stable? In the latter case, sort only leaves, but not nodes.

Always sort the tree in a meaningful way when it first loads.

The descending sort order must always be the exact reverse of the ascending sort order. Use a meaningful sort order. For example:

Sort text alphabetically
Sort numbers by their value
Sort status information by the severity of the status:
- Ascending: Sort status information from positive to negative, with neutral last.
- Descending: Sort status information from negative to positive, with neutral first.

- Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
- Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting the tree data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button

Resources

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

Elements and Controls

Table Toolbar (guidelines)
Table Overview (guidelines)
View Settings Dialog (guidelines)

Implementation

Tree (SAPUI5 samples)
Tree (SAPUI5 API reference)
Standard Tree Item (SAPUI5 API reference)
Custom Tree Item (SAPUI5 API reference)

Single Planning Calendar

The single planning calendar is a scheduling control that displays the calendar of a single person or resource over a day, work week, or week. Users can view appointments, create new appointments, and delete appointments.

Single planning calendar

Usage

Use the single planning calendar if:

You want to enable users to schedule or monitor the calendar of a single person or resource.
You want to offer multiple calendar views (day, work week, week).

Do not use the single planning calendar if:

You want to compare objects of the same type over a given period (for example, appointments for multiple persons or resources). In this case, use the planning calendar.
The main use case is to schedule all-day appointments, and you don’t need to see an hour axis. In this case, use the planning calendar.
You need a complex graphical representation or planning application involving activities, resources, hierarchical project structures, relationships, and so on. In this case, use the Gantt chart.

Responsiveness

The single planning calendar is responsive and supports the cozy and compact density modes.

Overflow Behavior

On smaller screens, the custom toolbar utilizes the overflow behavior of the standard SAP Fiori toolbar.

If the available actions do not all fit into the available space on the toolbar, an overflow menu button appears on the right of the toolbar. The rightmost actions move into the overflow menu first.

Single planning calendar - Size L

Single planning calendar - Size M

Single planning calendar - Size S

Components

The single planning calendar consists of the following components:

Header
Toolbar
View switch
Navigation
Date strip
All-day appointment
Timeline
Appointment
Calendar grid
Now marker

Components of the single planning calendar

Developer Hint

To prevent waiting time, app developers should load the sap.ui.unified library.

1. Header

The header contains the toolbar and the navigation.

2. Toolbar

The toolbar consists of the calendar title (optional) and the toolbar actions, including a default view switch. You can add other app-specific actions that are relevant for your use case (such as creating an appointment, search, filter, settings, showing the calendar legend, and so on). Always place actions that affect the entire calendar in the toolbar.

3. View switch

The view switch allows the user to switch between different time intervals. The default views are day, work week, week, and month. The app developer can choose which views to include, depending on the use case.

In the month view, all appointments for the respective day have the same width and height. Each grid cell can hold 4 appointments in compact mode and 3 appointments in cozy mode. The remaining appointments can be accessed with a # More link. In month view, all-day appointments look and behave like regular appointments.

Month view

You can also create custom views by setting a different number of visible columns in the grid. We only recommend doing this if your use case really requires it. You must also ensure that any custom views are responsive. For anything over 7 days, provide an alternative view for size S.

Custom view 10 days - size L

Custom view 3 days - size S

Developer Hint

If no view is set by the application developer, the single planning calendar renders the week view. If the application developer sets only the day view, the week view is not visible.

4. Navigation

The navigation area contains back and forward arrows, the Today button, a date interval link, and the date strip. Clicking the Today button takes the user to the period containing the current day.

5. Date strip

The date strip is the horizontal axis of the calendar grid, showing the currently visible day or days. Non-working days are a darker color.

6. All-day appointment

All-day appointments are appointments that take up 24 hours. They are located in a dedicated area below the date strip and above the first hour of the timeline.

The option to create all-day appointments must be added at application level. Consider using a switch or checkbox that automatically sets the start and end time of the appointment to 00:00. We recommend reflecting this in the UI for creating the appointment as well. For example, offer a date picker instead of a date/time picker for selecting the start and end of the appointment (as shown in the sample dialog).

There is no limit of the height of the all-day appointments area. However, if your use case involves a lot of all-day appointments (and their area takes up most of the screen), consider using the planning calendar instead.

7. Timeline

The timeline is the vertical axis of the calendar grid, showing the hours.

Creating an All-Day Appointment - Sample Dialog

8. Appointment

Each appointment can have an icon or image, a title, and a subtitle. If there is not enough horizontal space for the text, it is truncated. If an appointment has an icon, the icon remains visible as long as there is space for it, even if that does not leave enough space for the title. If there is not enough vertical space, the subtitle is not shown.

Appointments vary in height, depending on their duration, and in width, depending on how many appointments take place simultaneously. The minimum height of an appointment corresponds to a 30-minute appointment.

The app can set up to 20 types of appointments. Each type has its assigned color. Always choose appointment types with contrasting colors. Make sure that each type is also represented as a text, and not only by the color.

9. Calendar grid

The calendar contains the appointments and all-day appointments, and is controlled by the currently selected view. Non-working days have a darker background color in the calendar grid.

10. Now marker

The now marker is a horizontal line through the calendar grid, which indicates the current time. The current time is visible on the timeline. If the current time falls within 15 minutes of a full hour, it replaces the full hour.

Appointment structure

Now marker - Current time replaces the full hour

Single Planning Calendar Legend

You can highlight special days within the calendar. A legend is used to define the meaning of the highlights. Users open the legend using the legend icon button in the toolbar ( ). Like all other actions in the toolbar, the app developer must add the legend button explicitly.

For details, see the legend sections for the Planning Calendar and Calendar.

Guidelines

Ensure that colors are used consistently within your product area.

Single planning calendar legend

Behavior and Interaction

Date Picker

The visible period is indicated with the date interval link in the navigation. Clicking the link opens a date picker, which helps the user to navigate quickly to a specific day or week.

Creating an Appointment

We recommend offering a Create action in the toolbar.

The UI for creating the appointment must be implemented at app level. The control provides only the underlying functionality for creating appointments. For most use cases, a dialog works best and is recommended (see sample dialog below).

Sample Dialog for Creating an Appointment

First day of the week

You can set the day that displays as the first day of the week in the week and month views. Valid values are 0 to 6, starting with Sunday. If no value is set, the default of the used locale is used.

Zooming

To make appointments easier to read, you can implement the zoom behavior using the controls button, step input, or slider.

The scaleFactor property controls the zoom level. Its values can be numbers from 1 to 6. The number represents a multiplier for the height of the rows.

Viewing Appointment Details

The UI for viewing appointment details must be implemented at app level. The control provides only the underlying functionality for displaying appointment details. We recommend using a popover to keep the context for the user (see sample popover below).

Sample Popover for Viewing Appointment Details

Working Hours

You can opt to set working hours in the single planning calendar (properties: startHour, endHour). The non-working hours then have a different background and can be hidden (property: fullDay). You can also give the user the option to toggle between working and non-working hours. We recommend offering a toggle button in the toolbar (the button must be added by the app team).

Working Hours vs. Full Day

Sticky Header

To keep the context when the user scrolls down the calendar, the header area of the single planning calendar can remain fixed at the top of the screen (property: stickyMode).

At app level, you can choose to have the entire header area sticky (value: All) or only the Navigation area (value: NavBarAndColHeaders).

Drag and Drop

You can enable drag and drop for moving appointments (property: enableAppointmentDragAndDrop). Moving an appointment changes its start and end times (for example, if an appointment is scheduled from 1:00-2:00 PM, the user can drag it and change the time slot to 2:00-3:00 PM). When dragged, the appointment is shown as a ghost element on the mouse cursor. A placeholder indicates the target drop area.

Appointments can also be dragged from or to the area for all-day appointments. When the user drags an all-day appointment to the planning area, a placeholder shows the duration of the appointment after dropping (default = 1 hour). Similarly, dragging a regular appointment to the all-day appointments area transforms it into an all-day appointment (default = 1 day).

For desktop devices, you can also enable the following options:

Allow users to create new appointments by clicking, dragging, and releasing on an empty space in the content area (property: enableAppointmentsCreate).
Allow users to change the duration of an appointment by clicking and dragging one side of the appointment (property: enableAppointmentsResize).

Warning

To comply with the WCAG 2.2 accessibility standard, the control must offer an alternative to the drag and drop feature. Provide direct access via keyboard shortcuts, which enables single pointer users to make use of virtual on-screen keyboards. Alternatively, use a popover for appointment information and a dialog for creating appointments. For an example, see Single Planning Calendar – Create and Modify Appointments.

Drag and drop

Drag and drop into the all-day appointments area

Drag and drop from the all-day appointments area

Resources

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

Elements and Controls

Planning Calendar (guidelines)
Date Picker (guidelines)

Implementation

Single Planning Calendar (SAPUI5 Sample)
Planning Calendar (SAPUI5 Sample)
Single Planning Calendar (API)
Planning Calendar (API)

Planning Calendar

The planning calendar allows users to see different appointments at the same time and to create new appointments. It allows the user to display appointments for several objects, such as a team calendar, and compare them to each other.

Usage

Use the planning calendar if:

You want to compare objects of the same type with each other over a period of time.
You require responsive behavior.
You have less than 100 lines in the calendar.

Do not use the planning calendar if:

You want to show a calendar for one object and a detailed overview of appointments over a long time interval.
You want to show a complex or graphical representation. In this case, please use the Gantt chart.
You have more than 100 lines in the calendar. In this case, please use the Gantt chart.

Responsiveness

In size S, the control provides pop-in behavior, which allows the user to see as many appointments as possible and to connect them with the corresponding object. If the toolbar contains too many actions for the space available, the overflow icon appears.

The interval section displaying the hours, days, and months is responsive and shows 12 values in size L, 8 values in size M, and 6 values in size S. You can override this behavior, but you should then check that the responsiveness is still working.

Planning calendar - Size L

Planning calendar - Size M

Planning calendar - Size S

Types

You can define what size of interval the calendar should show, and whether multi selection should be possible. Additionally, the row header and the interval appointments are optional.

The control allows multi-select mode to be shown for the list items. This can be used, for example, to delete multiple objects from the view.

An app development team must decide whether to show the planning calendar with or without multi-select mode, or whether users should be able to switch between the two modes. Hiding the interval appointments of every object is optional.

The planning calendar can also be used without a row header. In this case, the row header disappears and only the appointments are visible. It can be used to show the calendar of one object. Note that the control was built mainly to compare time slots of different objects. For this reason, the time axis is shown horizontally and, depending on the interval, the appointments might shrink to smaller size. In this case, the text is cut off rather than truncated.

Components

This section describes the various components of the planning calendar.

Parts of the planning calendar

The control consists of different parts:

Header
Toolbar
View switch
Navigation
Time strip for hours/days/months
Row header
Row
List item
Interval appointment
Appointment

1. Header

The header contains the toolbar and the navigation.

2. Toolbar

The toolbar consists of the calendar title (optional) and the toolbar actions, including a default view switch. You can add generic and app-specific actions that are relevant for your use case (such as creating an appointment, search, settings, showing the calendar legend, and so on). Always place actions that affect the entire calendar in the toolbar.

For more information, check out the toolbar guideline article.

The generic actions are as follows:

Search
Create Appointment
Add New Contact (icon: add-contact)
Multi-Select Mode (icon: multi-select)
Legend (icon: legend)
Settings (icon: action-settings)
Full Screen (icon: full-screen/exit-full-screen)

3. View switch

The view switch allows the user to switch between different time intervals (calendar views). Depending on the number of available calendar views, the view switch can be a segmented button (four views or less) or a select control (five views or more).

The 1 Month view shows an entire month. On desktop devices, the 1 Month view always displays an interval of 31 days. When the displayed month is shorter (28, 29, 30 days), days from the following month are displayed. They have a different visual state and serve as navigation to the following month.

The 1 Month view has an additional style for half-column appointment distribution, which is mainly used to avoid overlapping. The property appointmentRoundWidth can be set to “HalfColumn” or “None” (default). Currently, the width of the appointment is always rounded to 12 hours.
Note: This property is also applied when the calendar interval type is Days and the view shows more than 20 days.

On size M and Size S, the 1 Month view is adaptive. It consists of a calendar and a list of appointments for the selected day.

If you offer the 1 Week view, we strongly recommend displaying a different number of days in the Days view (more or less than seven). Otherwise, the user might be confused, as navigation for the two views differs.

The default calendar views are Hours, Days, Months, 1 Week, and 1 Month. The app developer can choose which views to include, depending on the use case, and how many values are shown for each view. App developers can change the default number of values shown, but they should then ensure that the app is still responsive. The app developer can also create custom views.

Relative views

When you need to display a period that is not connected to a certain time/date, you can map the calendar to relative dates (in contrast to absolute dates, such as, “Week 1”, “Week 2”). For example, when you would like to divide the year into quarters.

The application developer specifies the names of the intervals in the time strip and the index picker, as well as the size of the interval. The index picker then configures how many days are in one interval. All this happens in the PlanningCalendarView, once the newly created relative property is set to “true”.

In addition, the application developer sets a minDate in the planning calendar, determining the start date of the relative views.

4. Navigation

The navigation area contains back and forward arrows, the Today button, a date interval link, and the time strip. Clicking the Today button takes the user to the period containing the current day. Clicking the date opens a date picker for direct navigation.

5. Time strip for hours/days/months

The time strip reflects the selected view, and shows the hours, days or months that are currently visible. The first day of the week can be defined. If not defined, the default is taken from the current user locale.

In all views that show days (Days, 1 Week, 1 Month), you can display calendar weeks in an extra line below the time strip (property: showWeekNumbers).

6. Row header

The row header identifies the object for which the appointments are shown. It pops in if there is not enough space. The row header can contain a picture or icon, a title, and a subtitle.

You can also add an action on the row header (event: rowHeaderClick).

7. Row

The row contains all appointments for an object. You can turn the alternating row coloring on or off. By default, the alternating rows option is turned on.

8. List item

The list item contains the row header, row, appointments, and interval appointments. Each row can show different working and non-working days.

If the users have a specific working schedule, the non-working days can be different on each row. This can be applied not only for weekends, but also for non-working days based on specific schedule differences.

9. Interval appointment

Each row can also have interval appointments, which differ from half-sized appointments visually and in that they are always at the top of the row. Interval appointments can be used to show appointments that last for a longer period of time, such as vacations or workshops.

You can opt to hide the space reserved for interval appointments if no such appointments exist for that time period.

10. Appointment

Appointments consist of an icon or picture, a title, and a subtitle. Concurrent appointments are shown one above the other.

There are four types of appointments:

Regular: Displayed in two rows. One-row display is also possible if the appointmentsReducedHeight property is set to “true”.
Half-size: Always displayed in one row, shows the title.
Large: Always displayed in three rows, also shows the description for each appointment (if available).
Automatic: The number of rows is determined automatically.

Appointment Info Rows

Title only 1 row

Title + text
or:
Title + description 2 rows

Title + text + description 3 rows

You can define the colors for different appointment types. Appointments can also be set to tentative.

The control can register a click event on the appointment, but the app development team must define what happens next.

In the Months view, appointments within the same calendar week are combined to save space. The combined appointment shows the number of appointments in the same week. If an appointment takes place between two calendar weeks (for example, from Sunday to Monday), it is not included in the combined appointments for either calendar week.

A list of the appointments in a combined appointment can be shown in a popover. However, this must be implemented by the app team. The control only provides the click event.

If necessary, you can disable combined appointments (property: GroupAppointmentsMode, value: “Expanded”).

Users can copy and paste appointments to a new position in the planning calendar using keyboard combinations (Ctrl/Cmd + drag and drop to the new position).

Planning Calendar Legend

To show the types for days and appointments, the planning calendar uses a specific legend control
(sap.m.PlanningCalendarLegend).

Users open the planning calendar legend using a standard legend button in the toolbar (). Like all other actions in the toolbar, the app developer must add the legend button explicitly.

The app team also needs to decide which container to use for the planning calendar legend. We recommend placing the legend in a popover to keep the context. You can also use a dialog, or, if there is sufficient screen real estate, show the legend as dynamic side content.

The planning calendar legend has two non-collapsible sections containing legend elements. By default, these are called Calendar and Appointments. The app developer can configure the section names using the itemsHeader and appointmentItemsHeader properties. If no elements are available for a section, it is not displayed.

The Calendar section contains standard legend items: Today, Working Day, Non-Working Day, and Selected (only in the 1-month view on mobile). The app team must ensure that the Selected element is added to the planning calendar legend when the planning calendar is viewed in 1-month mode in a smartphone size. This is not provided by the control. If any of the standard legend items are not needed, you can switch them off (property: standardItems).

You can also apply colors for special days in the Calendar section. The planning calendar legend does not automatically use the colors defined for special days in the planning calendar – this must be done by the app team.

Guidelines

Ensure that colors are used consistently within your product area.

The Appointments section contains the color values for the available appointment types. The app developer has to define explicitly which color represents which type. The planning calendar legend does not take the color automatically from the planning calendar.

If combined appointments in the calendar are of the same type (in Months view), they take the color of that type. Combined appointments of different types are marked gray. We also recommend adding the gray color for mixed combined appointments to the Appointments section in the legend.

Planning calendar legend

Developer Hint

To prevent waiting time, app developers should load the sap.ui.unified library.

Behavior and Interaction

To create an appointment, the user must trigger an action by clicking the Create button in the toolbar. You can also configure the control to create a new appointment when the user clicks directly on a row.

The user can click the appointment to see further details. The app development team must define what kind of information is then shown. For example, clicking an appointment can trigger a popover with detailed information.

Users can select more than one appointment at a time via Ctrl/Cmd + click. If the multipleAppointmentsSelection property is set to “true”, every appointment that the users click is selected.

A multi-select toggle can also be provided in the toolbar. This can be used, for example, to select multiple people in order to delete them from the planning calendar.

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

Depending on the current visible interval, appointments might be smaller and the text cut off. The user can click the appointment to see the details.

View switch

The user can change the calendar view with the select control (dropdown). For example, to get an overview of a whole year, the user selects the Months view. Which view is most useful depends on the average length of appointments and the use case.

Today

The user can trigger this action to go back to the current date/moment.

Back and forward navigation

The arrows allow the user to navigate to the next or previous interval.

Date picker

The user can open a date picker to select the start time for the visible interval. What is shown initially in the picker differs depending on the view. The current day is marked.

Snapping Header

The header area of the planning calendar can remain fixed on top of the screen (property: stickyHeader), which allows users to view calendars with a lot of rows without losing the context.

Header snaps to top when scrolling down

Drag and Drop

Drag and drop can be used to move appointments (to enable Drag and Drop use property: enableAppointmentDragAndDrop). Moving an appointment automatically changes its start and end times (for example, if an appointment is scheduled from 1:00-2:00 PM, the user can drag it and change the time from 2:00-3:00 PM) . When dragged, the appointment is shown as a ghost element on the mouse cursor. Drop target areas are indicated to the user with a placeholder.

In the “Hours” view, the appointments can be moved to a specific new time, with the placeholder snapping at every 30 minutes. In the “Days” view, the appointment can be moved to a different day. The placeholder indicates the target day. On drop the appointment is moved to that day but keeps its previous start and end hour. The interaction is the same for the “Months” view. The placeholder indicates the target month and, when dropped, the appointment is moved to that month. The start and end hour and start and end day remain the same.

Appointments can be moved between rows. Note that additional coding may be needed to determine whether all calendar users will be able to perform this action.

Users can create new appointments by clicking, dragging and releasing on an empty space in the content area. The control also allows users to change the duration of an appointment by clicking and dragging one side of the appointment container. These two options are only available for desktop devices.

Combined appointments and interval appointments are not draggable.

Drag and drop is only available on supporting browsers.

Warning

To comply with the new WCAG 2.2 accessibility standard, the control must offer an alternative to the drag and drop feature. Provide direct access via keyboard shortcuts, which enables single pointer users to make use of virtual on-screen keyboards. Alternatively, use a popover for appointment information and a dialog for creating appointments. For an example, see Planning Calendar – With Appointments Modification.

Drag and drop

Guidelines

Switching the Row Header

To enable end users to rearrange the planning calendar by switching the row header, you can implement a flexible row header. This is not done by the control and must be implemented by the app development team.

The list items in the row header can be a value of any attribute of an appointment. The appointment attributes are part of app-specific content, so they should be specified by the app development team. The control does not provide default attributes.

Our guideline is to use the select control in the place of the calendar title. The select control will contain all the attributes that can serve as the row header. When a different attribute is selected, the calendar is rearranged accordingly. You can also add a counter after the list items to indicate how many appointments fall into a specific group.

It is also possible to have both the calendar title and select control, in which case you should have first the title and then the select.

On small screen sizes, use select instead of the calendar title. If you want to keep the calendar title, place select in the overflow menu.

Select control in place of the title

Resources

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

Elements and Controls

Overview Toolbar (guidelines)
Calendar Date Interval (guidelines)
Date Picker (guidelines)

Implementation

Planning Calendar (SAPUI5 samples)
Planning Calendar Row (SAPUI5 API reference)
Planning Calendar View (SAPUI5 API reference)
Team Calendar (SAPUI5 sample)

List

In SAP Fiori, we distinguish between tables and lists. Both usually contain homogeneous data, but lists generally have rather basic data, whereas the data in tables tends to be more complex. Lists are mostly used in list-detail scenarios using the flexible column layout, as well as in popovers or dialogs. For certain use cases, lists can also be used in the dynamic page layout.

Usage

Use the list if:

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

Do not use the list if:

You want to manage complex datasets that need to be extensively sorted, grouped, filtered, or edited. In this case, use a table.
You work with complex hierarchies. In this case, use a tree.

Responsiveness

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

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

List Item Variants

The list contains various list items. These items can be of various types depending on the use case and on the content they have. SAPUI5 already provides the most common list items in SAP Fiori in the form of controls, although custom list items can also be created if necessary.

All the available list item types behave responsively and adapt to changing screen sizes out of the box. Most of them use truncation if size becomes too limited, since they are usually used to navigate to the item details. For custom list items, you can also wrap the texts, if required.

Object List Item

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

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

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

For more information, see object list item.

Object list items

Standard List Item

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

For more information, see standard list item.

Standard list items

Display List Item

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

For more information, see display list item.

Display list items

Action List Item

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

For more information, see action list item.

Action list item

Feed List Item

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

For more information, see feed list item.

Feed with feed list items

Input List Item

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

For more information, see input list item.

Input list item

Components

The list control comes with the following main properties:

Header

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

Footer

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

Lazy Loading

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

List with header and footer

Empty List

Avoid empty lists. If necessary, provide instructions on how to fill the list with data (sap.m.List/ sap.m.ListBase, properties: noDataText, showNoData).

Examples:

If a list is initially empty, provide at least a basic text:
No items available.
Overwrite this whenever a hint can be provided on how to fill the list with data.
If a list is used together with a filter bar (as in the list report), and is initially empty, use the following text:
No filters set. To start, enter your search and filter settings and run the search.
If a list is used together with a filter bar and the filter does not return results, use the following text:
No items found. Check the search and filter settings.

Adapt the texts above if:

The standard text is not precise enough for your use case (for example, no search is offered, only the search is offered).
You are using the live search (no Go button in the filter bar). In this case, leave out “run the search”.
The standard text is misleading (for example, if the data is filled based on a list-detail pattern instead of search and filter settings).

Empty list

Count

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

Standard list items with counter

Read/Unread

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

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

Display list item with read and unread items

Highlight Items

To show that an item needs attention, a highlight indicator can be shown in front of the item. The highlight indicator can be used to indicate:

A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted items using status colors

Highlighted items using indication colors

Behavior and Interaction

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

List Level

Scroll

The height of the list is defined by the number of items it contains. It does not have its own scroll container, but is scrolled together with the app.

If the list works in a “growing” mode, it only loads a few items at first. Additional items are only loaded (and rendered) on request. The “request” can either be triggered by scrolling (preferred), or by clicking the More button.

When the user scrolls, the title and the filter infobar can stick to the top of the surrounding layout container (sap.m.List, property: sticky).

Information

The “sticky” feature comes with some limitations:

It is not available on all browsers. In non-supporting browsers, the corresponding areas are not fixed on top of the surrounding layout container while scrolling.
Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the list is placed within the object page.
If the focus is set to a sticky area, the list is automatically scrolled to top.

Sticky title

Mode

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

None
SingleSelectMaster (used to pick one item with no additional indicator, as in the list-detail scenario with the flexible column layout)
SingleSelectLeft (used to pick one item using a radio button on the far left)
MultiSelect (used to pick several items from the list using checkboxes on the far left). The Shift key can be used to select a range.
Users can (de)select all items using CTRL+A. Select All (de)selects all items that the user can reach by scrolling.
Delete (used to delete items from the list using a delete indicator on the far right)

Guidelines

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

Developer Hint

In multiple selection mode, users can (de)select all items using the shortcut Ctrl+A. This only affects items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded (for example, items added via lazy loading with growingScrollToLoad). This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

To process all items, listen to the selectionChange event and to its flag selectAll. This indicates whether Ctrl+A was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

List with explicit single selection

List with multiple selection

List with delete mode

Grouping

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

Grouped list

Line Item Level

Type

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

The items can be one of the following:

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

The example shows how all these types are visualized.

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

Indicate Navigated Item

When multi-selection 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 only (multi-selection list with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.ListItemBase, property: navigated).

Navigated item

Swipe

You can provide a swipe feature (sap.m.List, properties: swipeDirection, swipeContent) for approving or deleting items quickly without having to look at the details. Swiping is possible in both directions (left to right / right to left). You can provide different actions for each direction. Because swiping is only available on touch devices, only offer it as an additional feature. Swiping should never be the only way to perform the action.

List with swipe action

Context Menu

The context menu can be triggered for the list or per item.

It gives users an alternative way of modifying the focused elements by giving access to context-specific functions.

Context menus are opened by right-clicking (desktop), long press (mobile), the CONTEXT MENU KEY, or Shift+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

List - context menu

Drag and Drop

One or several items can be repositioned within a list or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop

Whole item as drop target

Styles

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

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

List without separators

Guidelines

Text Length

When you use the list in the first column of the flexible column layout, keep the texts as short as possible and only as long as necessary. If you expect large numbers, use formatting instead.

Design for Performance

To optimize performance, we recommend showing no more than 200 items at once in the list. For larger datasets (up to 1,000 items), use the “growing” mechanism to limit the number of displayed items, and make sure that users can filter the data.

Warning

The limits above are only recommendations. For a specific app context, the number of manageable items might be far higher or lower.

The actual limits depend on your concrete scenario, including:

The number of rows in the table
The number of displayed columns
The complexity of the cell content (for example, simple text vs. complex charts)
Other elements on the page (for example, multiple pages in a flexible column layout, or several tables/elements with more complex rendering on one page)
The browser being used

Custom List Items

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

When creating custom list items, take the following guidelines into account, as needed:

Radio Button

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

Errors and Warnings

To indicate that the list contains items with errors or warnings, show a message strip above the list. On the message strip, provide information about errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

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

Developer Hint

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

List containing errors

Actions

To trigger actions on single items, show the actions on a toolbar above the list. Do not offer actions on multiple items if the list is expected to have fewer than 10 items in most cases.

The following actions on single items must always be inline:

Delete: Use “Delete” mode (sap.m.Tree / sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This places a Delete button at the end of each item.
Navigation: Use the “Navigation” item type (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This places a navigation indicator at the end of the corresponding items. Use this to navigate to a new page containing item details.
Edit: Use the “Detail” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail). This places an Edit icon at the end of the corresponding items.

You can combine delete and edit actions, or delete and navigation actions. However, edit and navigation actions cannot be combined.

To trigger actions that are independent of the selection, show the actions on a toolbar above the list. For example: Add, Collapse All, Expand All, … .

To trigger a default action on the entire item, use the “Active” or “DetailAndActive” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Active). When clicked, active items trigger an event that can be handled by the app (for example, to open a dialog). Selection of items and expanding/collapsing a node do not trigger the event, and are handled by the tree. Do not use the active item type for navigation, to switch the line item to an edit state, or to delete the item.

Active can be combined with edit and delete, but not with navigation. Do not combine active with the single selection master.

Add Items

For adding items, place an Add or Create text button on the toolbar.

Use Create if the button adds a brand new item that doesn’t yet exist on the database.
Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the list, with a visual highlight at the beginning of the row.

Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

There are three options for adding an item. In order of priority, these are:

Add the item inline. Create an empty, editable item as the first item of the list. Show the Save button on the toolbar of the list. This option is recommended for simple scenarios where just a few input fields have to be filled.
Open a dialog for items with up to 8 input fields. Save the new item at dialog level.
Navigate to a new page. Only use this behavior for very complex scenarios that cannot be handled by a dialog (for example, creating complex objects). When the user presses Save in the footer toolbar of the create page, navigate back to the list.

Depending on the flow, an item can be in one of three different states:

New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the list. Ignore current sort, filter and grouping criteria to keep the item visible.
Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
- Inline creation: After Save was triggered on the toolbar or at page level
- Create with dialog: A list showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

In the context of draft handling new items are not saved on list level, but rather with the entire draft.

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

Drag and Drop

Warning

To comply with the WCAG 2.2 accessibility standard, the control must offer an alternative to the drag and drop feature. Use the Move Up and Move Down buttons on the toolbar.

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, provide the corresponding keyboard support, and are available for all browsers.

Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within the list, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop targets in between items

Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on values, the dropped item needs to take on the corresponding value of the target group. If this is not wanted, do not allow users to rearrange items in grouped lists.

Example:

A list is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Don't

Do not combine rearranging items with grouping, unless you know exactly what you're doing

View Settings

Provide individual buttons for each of the following settings on the toolbar of the list: sort, filter, group.
Clicking one of these buttons opens the view settings dialog or P13nDialog dialog with just the relevant page inside.
When closed, apply the settings to the list accordingly.

Keep the following in mind:

Do not offer any of these features if the list is expected to have only a small number of entries (up to 20 in most cases).
If filtering is a main use case, do not offer filtering on the toolbar of the list. Use the filter bar instead.
Only use the view settings which are really needed. For example, do not offer grouping if it does not support your use case well.
Keep the view settings consistent. When a user reopens the app, show the list with the same sort, filter, and group settings as last defined by this user.

Sort

For the default sort setting, sort by the item title, which is usually the identifier of an item.
If you offer sorting, offer it for each data point available in the item. Allow sorting in both directions, ascending and descending. The descending sort order must always be the exact reverse of the ascending sort order.
For each data point, provide a meaningful sort order. For example:
- Sort text alphabetically
- Sort numbers by their value
- Sort status information by the severity of the status:
  - Ascending: Sort status information from positive to negative, with neutral last.
  - Descending: Sort status information from negative to positive, with neutral first.
  - Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
  - Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Filter

To display the current filter state, use the infobar below the title. Clicking the infobar opens the filter page of the corresponding dialog.
Show the infobar only if the filter settings are not shown somewhere else. For example, do not show the infobar for settings located in the filter bar or in a select control placed in the toolbar of the list.
If the infobar is shown, provide an option to reset all corresponding filters on the infobar.
Keep the infobar sticky (sap.m.List, property: sticky).

Export to Spreadsheet

Apps can provide a menu button for exporting list data to a spreadsheet (for example, on the relevant toolbar). For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button

Resources

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

Elements and Controls

Action List Item (guidelines)
Action Placement (guidelines)
Display List Item (guidelines)
Feed List Item (guidelines)
Flag and Favorite (guidelines)
Formatting (guidelines)
Input List Item (guidelines)
Object List Item (guidelines)
Standard List Item (guidelines)
UI Element States (guidelines)

Implementation

List (SAPUI5 samples)
Object List Item (SAPUI5 samples)
Standard List Item (SAPUI5 samples)
Display List Item (SAPUI5 samples)
Action List Item (SAPUI5 samples)
Feed List Item (SAPUI5 samples)
Input List Item (SAPUI5 samples)
List (SAPUI5 API reference)
Object List Item (SAPUI5 API reference)
Standard List Item (SAPUI5 API reference)
Display List Item (SAPUI5 API reference)
Action List Item (SAPUI5 API reference)
Feed List Item (SAPUI5 API reference)
Input List Item (SAPUI5 API reference)

Action List Item

The action list item control lets the user trigger actions directly from a list. It is used mainly within dialog boxes and popovers.

Action list items

The following figure shows examples of popovers for a chart with one and three related actions.

Chart popovers using action list items

Behavior and Interaction

List item behavior and interaction is similar for all list item variants and is therefore described in the list overview article.

Resources

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

Elements and Controls

Chart Popover (guidelines)
List (guidelines)

Implementation

Action List Item (SAPUI5 samples)
Popover (SAPUI5 samples)
Action List Item (SAPUI5 API reference)
Popover (SAPUI5 API reference)

Feed List Item

Action Select

Empty Page

Date/Time Input

Bubble Chart and Time Bubble Chart

Color Use for Primary Values and Quantitative Ranges

Bullet Chart – Color Use for Primary and Projected Values

Size of Data Points

Chart – UI Theme Designer for Color Palettes

Object Identifier

Object Number

Chart – Primary Data

Chart – Secondary Data

Chart – Behavior and Interaction

Scrolling Direction of a Chart

Object Header

Bullet Chart – Color Use for Primary Values

Menu Button

Contextual Filter

Checkbox

A checkbox lets the user set a binary value (such as “true/false”). When the user clicks the checkbox, it toggles between checked and unchecked. Checked means that the state described by the checkbox text applies, or that the item has been chosen.

The checkbox text describes the positive action (as in “true” or “yes”). The text can be either a label control to the left of the checkbox, or a checkbox text that appears to the right of the box.

If there is only one checkbox, you can use a label or text depending on the form format.
If there is more than one checkbox, the label describes the whole group of checkboxes. In this case, use the text property of the checkbox to describe the individual checkboxes.

Within a group of checkboxes, each checkbox can be checked or unchecked. The user can check multiple options.

A checkbox does not apply a setting right away; the changes take effect after user confirmation via a triggering action button (such as Save).

Checkbox enabled/disabled

Usage

Use the checkbox control if:

Only one option can be selected or deselected, for example to accept terms of use. Use it only if the meaning is obvious (single checkbox).
You have a group or a list of options that can be selected independently of each other (checkbox group).
Your use case requires all available options to be displayed right away without any user interaction (also in read-only cases).
The values of the option list are primary information and need to be displayed right away.
Changes to the settings need to be confirmed and reviewed by the user before they are submitted. This helps prevent users from changing settings accidentally.
You want to group multiple suboptions under a parent option, and require an intermediate selection state (tri-state). The tri-state indicates that some (but not all) suboptions are selected.

Do not use the checkbox control if:

The user needs to choose multiple options from a large list. Use a multi-combo box instead.
The user can choose only one option from a list. For a small list, use a radio button group instead. For a large list, use the select control or a list with multi-selection functionality.
You want to offer two options for a “yes/no” or “on/off” type of decision. Consider using a switch control instead.
The user needs to perform instantaneous actions that do not need reviewing or confirming. Consider using the switch control instead.
There is not enough space available on the screen. Use the combo box control instead.

Responsiveness

A checkbox can appear in two different sizes. In cozy mode, it is bigger than it is in compact mode. This makes the checkbox easier to select on touch devices. For more information on cozy and compact modes, see the article on content density.

Compact and cozy mode

In both sizes, the touch/click area around the checkbox is bigger than the checkbox itself, making the checkbox easier to select. Clicking inside this area toggles the checkbox.

Note: Because the touch/click area does not include the label on the left, clicking the label will not toggle the checkbox.

Checkbox touch/click area without label

Checkbox touch/click area with label

Layout

The checkbox control consists of a box and a text that describes the purpose of the checkbox.

If the checkbox is checked, an indicator is shown inside the box.

Although the clickable area to select/deselect a checkbox covers a wider area than the box (see the Responsiveness section), the focus is indicated by a dotted line that surrounds only the box.

If the checkbox appears alone inside a form, the text can be omitted if the label in front of the checkbox takes over its function.

Note: Because the touch/click area does not include the label on the left, clicking the label does not toggle the checkbox.

If there are several options to choose from in a form, the label describes the entire checkbox group, and the texts describe the individual checkboxes.

Since checkbox texts are also a type of label, use title case to be consistent with other labels. If the label is long, it can wrap in order to fit the text into the visible area of the content holder. There is no limit on the number of lines a text can wrap.

Exception: If one or several of the checkbox texts is very long, or is formulated as a phrase, use sentence case and appropriate ending punctuation.

For forms with labels above the fields, place the label above the checkbox group, or do not use a label. For a single checkbox, use only a checkbox text.

For forms with labels to the left of the field, place the label next to the group, aligned with the first checkbox field, or do not use a label. For a single checkbox, use only a label, or only a checkbox text.

Developer Hint

Do not use empty labels to arrange the checkboxes. Creating a label in front of each checkbox and leaving the text empty looks fine – nobody sees the label, and the checkboxes are aligned correctly underneath each other. However, the screen reader will notice these labels and read each of them as “label”. Instead, use the layout data property (layoutData) for the checkbox. In this property, force a line break (linebreak) and set the value of the indents in sizes L and M (indentL, indentM) according to the value of the label span in the simple form (labelSpanL, labelSpanM).

Checkbox layout

Short checkbox text in title case; Long checkbox text in sentence case

Checkbox text wrap

Checkbox group with label aligned to the left or on top

Checkbox group without label

Single checkbox with label or with text

Behavior and Interaction

Clicking a checkbox toggles the state of the checkbox between checked and unchecked.

Tri-State

The main purpose of this state is to represent the mixed selection states of dependent input fields. If some (but not all) of the dependent fields are selected, the checkbox shows a partially selected state. This is only a visual state and can’t be achieved by a direct user interaction.

Checkbox interaction states

Properties

You can set the width of the element containing the checkbox and the text manually (property: width).

If the text exceeds the available width, it can wrap. The touchable area for toggling the checkbox ends where the text ends.

If the width allows more space than the text requires, white space is added. The touchable area for toggling the checkbox is increased according to the manually-set width.

The text can be positioned manually in this space (property: textAlign). However, we do not recommend using the right-align option, which can result in a large amount of white space between the checkbox and the checkbox text.

States

If a checkbox is part of an editable form, it can be edited in when the form is in edit mode. In display mode, the checkbox uses its “display-only” state (property: displayOnly), and two icons replace it to represent the checked and unchecked states.

If the checkbox appears in a read-only form, set the checkbox to read-only (property editable = “false”).

Do not combine the settings “disabled” and “read-only”. This is technically possible, but does not make any sense.

The checkbox can represent a mixed selection state, or tri-state (property: partiallySelected). The visual state depends on the value of the selected property.

Don't

Checkbox text - Don't format the checkbox incorrectly

Checkbox interaction value states

Resources

Elements and Controls

Label (guidelines)
Combo Box (guidelines)
Multi-Combo Box (guidelines)
Radio Button (guidelines)
Select (guidelines)
Switch (guidelines)
How To Use Semantic Colors (guidelines)

Implementation

Checkbox (SAPUI5 samples)
Checkbox (SAPUI5 API reference)

Button

Buttons enable users to trigger actions. There are 4 button types:

Simple button for one action
Toggle button to switch between different states
Segmented button with a group of options
Menu button with a group of actions

Usage

Use the button types as follows:

Use simple buttons for specific actions, such as:
- Create, Edit, Save
- Approve, Reject
- Accept, Decline
- OK, Cancel
Use toggle buttons in a toolbar to activate or deactivate an object or element. You can also use toggle buttons to switch between different states.
If you want the user to select one option from a small group, offer a segmented button in the toolbar. For example:
- Year, Month, Day
- Small, Medium, Large
Use the menu button if you need a menu that provides more than one option.

Do not use buttons if:

You want to link to a different page or object. Use the link instead.
You want to let users upload content. Use the upload set control instead.

Common button types

Types

Button

Buttons can trigger primary, secondary, semantic, and negative path actions. These different action types are explained in more detail in the action placement guideline.

Header and Footer Toolbars

Use the following button styling for the different action types in the header and footer toolbar:

Primary action: Use the emphasized button style. Note that there can only be one primary action per page.
Secondary action: Use the default button style. In SAPUI5 you must implement type=”ghost” to achieve this style in the header and footer toolbar.
Negative path action: Use the transparent button style.
Semantic action: Use the semantic buttons for positive and negative actions. Use the “Accept” style for positive actions, and “Reject” for negative actions. Semantic actions must always be text buttons.

Content Toolbars

Use the following button styles in content toolbars for tables, forms or charts:

If the single primary action for the whole page is in the toolbar, use the emphasized button style.
If the single primary action for the whole page is not in the toolbar, highlight the most important button in the toolbar with the default button style.
For secondary actions and negative path actions, use the transparent button style.
For split buttons and menu buttons, use the transparent button style.
Do not use semantic button styles.

Button types

Toggle Button

A toggle button switches between two actions. One of the actions is always active, one is inactive. Use the toggle button for secondary actions.

Apply the following button styles for the different toolbars:

Header and footer toolbars: Use the standard button style.
Content toolbars: Use the transparent button style.

Do not use any other styling types and ensure the button label communicates the toggleable nature of the button.

Toggle button - Regular state

Toggle button - Pressed state

Segmented Button

A segmented button shows a group of options. Only one of the options can be active, the others remain or become inactive. Pressing an option activates it. By default, the control for segmented buttons calculates the button width and applies it to all buttons within the group. You can change this by setting the width for individual buttons.

The segmented button is comparable to a radio button group control.

Segmented buttons

Menu Button

There are two types of menu buttons. Both can contain items and submenus.

Standard Menu Button

When the user activates the button, the menu opens. This is the default type.

Split Menu Button

The split menu button is separated into two areas: the text and the arrow icon. The separator between them signals that the two areas result in different actions. The user has two choices: activating the text on the button triggers the action. Activating the arrow opens the menu. The split button consolidates a variety of commands, especially when one of the commands is used more often.

In split mode, the text depends on the default action. If the default action is displayed as an icon only, all the menu items must contain icons.

Split Menu Button Behaviors

The split menu button can have two different behaviors:

The button always triggers the default action set by the app developer. If no default action has been defined, the first item in the menu list becomes the default.
The button triggers the last action chosen by the user. Initially, it also triggers the default action. However, when the user selects a different action, this user action becomes the default, and the button text changes accordingly. The button has a fixed size and the text truncates if the menu item exceeds the available width (as with the combo box).

Standard menu button

Split menu button

Button Content

Text or Icon

A button can contain an icon OR a text.

Always use a text button for primary, secondary, semantic, and negative path actions.

Use icon buttons only if the icon metaphor is easily recognizable. Ideally, it should have same meaning worldwide. For more information about icons in general, check out the article on iconography.

Badge

Buttons with text (left) and icon (right)

The standard button can contain an optional badge. The badge acts as a visual eye-catcher and attracts the user’s attention. It shows a number and is typically applied in browse and collect use cases. For example, it can display the number of items in a shopping cart.

Only use the badge in combination with the emphasized and secondary button styles. The number of the badge must always be a whole number (1, 2, 3, …) and cannot be smaller than 1. If 0 or minus items are in the basket, the badge is not displayed. If the number exceeds 4 characters, such as 9999, it is truncated to 999+.

The position of the badge (attached to or on a button) can vary depending on the content density.

Buttons with a badge in cozy mode (left) and compact mode (right)

Behavior and Interaction

Buttons can be triggered through mouse, keyboard, touchscreen and screen reader interaction.

A button provides visual feedback for “hover”, “press-down”, and “focused” states.
A toggle button remains in the pressed state until it is pressed again.
In a segmented button, the chosen option stays active until the user presses one of the other options.
A menu button displays a dropdown menu on activation.
In a split button, selecting the button text triggers that action directly. Activating the arrow opens a dropdown menu. If the user selects a menu item, the action is triggered and the menu closes.

If an action cannot be triggered, or is temporarily unavailable, use the disabled state for the corresponding button.

If you want to switch a text, icon or tooltip after a button click, bear in mind to use the invisible message control to also convey the information to screen reader listeners.

All three button types support the cozy and compact form factors. For more information, check out the article on content density.

Regular state

Hover state

Pressed state

Disabled state

Focused state

Responsiveness

Simple Button

The simple button usually grows to fit the size of the text. If you set a fixed size for the button, the text truncates.

If the button is used in a responsive container or toolbar, it follows the responsive behavior defined for that element. For example, the button can move to another line.

Buttons with different lengths

Menu Button

The maximum width of the menu button is 12 rem (192 px). If the button text exceeds the maximum or fixed width, it truncates.

On tablet and desktop devices (sizes M and L), the menu button triggers a cascading dropdown menu.

On smartphones (size S), the menu opens in a full screen dialog, and the button label becomes the title of the dialog. The footer contains a Cancel button. Items with submenus become navigable. Navigation is similar to that used in a popover, with a Back button.

Open menu button - Size M/L

Menu button popover - Size S

Guidelines

Button Text

Choose a button text that is short and meaningful. Check out the UI text guidelines for more information.
Use a verb in the imperative for all actions (for example: Save, Cancel, Edit).
Note: The grammatical form for actions can differ for other languages. For example, German action labels use the infinitive (Sichern, Abbrechen, Bearbeiten).
Keep in mind that the text can be up to 300% longer in other languages.
If you need to show the number of items that will be affected by the action of the button, you can add the number in parentheses. For example, Edit (3).
Do not change the text or icon of a toggle button when it is pressed. Screen readers announce the “pressed” state for the action. If you use a different text for the pressed state, the screen reader announcement doesn’t make sense.

Icon Buttons

Make sure the default accessibility text for the icon is correct for your use case. If the text is not ideal, define an app-specific accessibility text.
Offer a tooltip to show the label for icon buttons.
Don’t use the icon control for buttons. Use the icon property for the button instead.

Button Shortcut

You can show the keyboard shortcut for an action. The keyboard shortcut appears on hover or on keyboard focus, and its positioning (top or bottom) is context-dependent. When a tooltip is needed, it is combined with the shortcut information.

Developer Hint

To show a keyboard shortcut, use sap.ui.core.CommandExecution. Do not use a tooltip.

Button with a shortcut hint

Usage

Use the analytical table (ALV) if:

The cell level and the spatial relationship between cells are more important than the line item. Examples include spreadsheet analyses and waterfall charts. Note that an analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
You have to work on more than 1,000 rows. In this case, the analytical table is easier to handle. In contrast to the responsive table, the architecture of the analytical table is optimized for handling large numbers of items. Note that an analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
Comparing items is a major use case. In this case, an analytical table might be more appropriate than a responsive table. In the analytical table, each cell contains only one data point. In contrast, the responsive table is more flexible regarding line items, including the ability to add more data points per cell and also the pop-in function. Both make comparisons more difficult. Note that an analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.

Do not use the analytical table (ALV) if:

You need a table. The responsive table is the default table in SAP Fiori. Additional use cases where you might need the responsive table include:

- You need to provide a total sum for one column. You can also add totals to the responsive table.
- The focus is on working on line items, not on cells. The responsive table is optimized for displaying complete items on all devices (such as purchase orders and purchase requisitions).
- Selecting one or more items is a main use case and details are needed to choose the correct item.
- Line items are independent of each other and no operation across columns is needed.
- You want to have only one implementation for all devices.

The main use case is choosing one item from a very small number of items with no additional details. A select or combo box might be more appropriate.
The main use case is choosing one out of several items with only a few details per item. A list might be more appropriate. Examples include the list in a list-detail scenario or an attachment list. Pay attention to the layout of the list item to ensure that it has a pleasant appearance.
You cannot provide an analytical binding on the technical side. In this case, a grid table will do the work. However, please note that the grid table doesn’t provide grouping, aggregation options, and is not responsive.
Data needs to be structured in a hierarchical manner. In this case, a tree table might be more appropriate. Although the analytical table can have several grouping levels, it is not as flexible when nodes at several levels contain children. Note that neither the tree table nor the analytical table are responsive. You will need to take an adaptive approach by offering an additional UI for smartphones and tablets.
You need an overview of a large amount of data. In this case, use charts.
You just need it for layout reasons. In this case, use a layout container like HBox or VBox.
You need read-only or editable field-value pairs. Use a form instead. The analytical table is not optimized for form-like input navigation.

Responsiveness

The analytical table is available for desktops and tablets, but not in smartphone sizes. It supports touch 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.

Analytical table (ALV) shown on a desktop

Analytical table (ALV) shown on a tablet

Components

An analytical table does not consist of other elements. However, it is common to use a toolbar above the analytical table.

The toolbar can contain entry points for the view settings dialog and the table personalization dialog or for the p13n dialog, as well as for view switches in the form of a segmented button, and buttons for Add, Edit, and other actions.

Behavior and Interaction

An analytical table is quite restricted in terms of its content, although it provides powerful features for working with the content.

Table Level

Scroll

An analytical table allows horizontal and vertical scrolling (sap.ui.table.AnalyticalTable, property: navigationMode, value: Scrollbar).

You can add any number of line items to the analytical table, which is known as “lazy loading”.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.AnalyticalTable, property: rowHeight).

The analytical table is optimized to allow faster scrolling within the first 1000 items.

Scroll bar

Select

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

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

Analytical table without item selection

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

Analytical table with single selection

Multiple selection: One or more items can be selected. The analytical table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back. The Shift key can be used to select a range. For multiple selection, you can choose between two variants.
- Multi-toggle mode (property: selectionMode = MultiToggle)
- Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)
These variants behave differently when the user selects more items than are currently loaded in the front end.

Multi-toggle

In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end (keyboard: Ctrl+A). All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

Multi-selection plug-in

If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:
- By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
- You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
  - The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and a message can appear (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
  - If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets. (Keyboard: Ctrl+A)
- If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.

Information

When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
The “minimum limit”: Internally, the analytcial table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.AnalyticalTable, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

Analytical table with multiple selection

Using the multi-selection plug-in with a limit

Selection Behavior

An item can be selected in different ways, depending on the configuration of the analytical table (sap.ui.table.Table, property: selectionBehavior):

Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection tables if clicking a row or a cell is not used for anything else.
RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection tables if clicking a row or a cell is not used for another purpose, such as navigation.

Compact, Cozy, and Condensed

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

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

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

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

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

Analytical table in compact mode

Analytical table in condensed mode - More items on the same screen real estate

Column Header

The column header provides the label for the corresponding column and access to the column header menu.

Columns are resized as follows:

Mouse interaction: The user drags the separator line between two columns (sap.ui.table.AnalyticalColumn, property: Resizable). Double-clicking the line optimizes the column according to the length of the data currently visible and the label of the column header (sap.ui.table.AnalyticalColumn, property: Autoresizable).
Touch interaction: The user clicks the column header to reveal two buttons: one to show the column header menu and one for resizing. The user drags the latter to resize the column.
Keyboard interaction: Users can increase the width of the focused column header with Shift+Right and decrease it with Shift+Left.

When the user resizes a column, the adaptation of the column width depends on how the column widths are set:

If column widths are set in pixel-based units (px, em, rem), the resized column is adapted and subsequent columns are moved accordingly. The width of all other columns is not affected.
If all the columns together do not use up the full width of the table control, empty space is added. If all the columns together exceed the width of the table control, a scrollbar appears.
If all column widths are set as percentages or “auto”, resizing one column automatically resizes one or more other columns. Resizing can also affect the position of the resized column. This option utilizes the full width of the table and ensures that no white space is added. A scrollbar appears only if all or most of the columns become to narrow. To avoid the side effect of undersized columns, you can set a minimum width per column. However, this minimum width is only taken into account if columns are resized automatically. End users can still reduce the column width to below the defined minimum (sap.ui.table.Column, properties: width, minWidth).

Users can rearrange columns by dragging the column header to another position (sap.ui.table.AnalyticalTable, property: enableColumnReordering). Keyboard interaction: Ctrl+Left and Ctrl+Right move the focused column header one position in the corresponding direction.

Column header

Opening the column header menu on touch devices

Columns do not use up the available space

Column Header Menu

For each column, a menu can contain the following menu items (sap.ui.table.AnalyticalColumnMenu, property: Visible):

Sort Ascending/Descending (sap.ui.table.AnalyticalColumn, property: showSortMenuEntries)
Free text filter (sap.ui.table.AnalyticalColumn, property: showFilterMenuEntries)
Group
Totals
Freeze from the first to the last specified column (sap.ui.table.AnalyticalTable, property: enableColumnFreeze)

For each column, the menu can be replaced by an app-specific menu.

Column header menu

Sort

The column header menu can provide two sort options (sap.ui.table.AnalyticalColumn, properties: sortProperty, showSortMenuEntry):

Sort Ascending
Sort Descending

The user selects one of these options to sort the corresponding column accordingly (sap.ui.table.AnalyticalColumn, properties: sorted, sortOrder, sortProperty).

Sort settings in column header menu

Filter

The column header menu can provide a search field for entering free text (sap.ui.table.AnalyticalColumn, properties: filterProperty, showFilterMenuEntries).

If the user enters a term in the input field and triggers the search by pressing ENTER when the focus is on the filter input field, the analytical table is filtered by the corresponding column and value (sap.ui.table.AnalyticalTable, properties: filtered, filterProperty, filterValue, filterOperator, sap.ui.table.AnalyticalColumn, property: filterType).

Note that the filter may return zero results, in which case, the table might be empty.

General recommendations for filtering:

If filtering is a main use case, choose the filter bar or any other filtering UI over the built-in free text filter.
Only use the free text filter if filtering is a secondary use case and if the filter bar is too heavy.

Free text filter in column header menu

Group

The column header menu can provide the option to group by this column (sap.ui.table.AnalyticalColumn, property: sortProperty).

One group collects all items with the same value within the corresponding column.

Group setting in column header menu

If line items are grouped in a column, every group is provided with a collapsible or expandable group header (sap.ui.table.AnalyticalColumn, property: grouped). The header text consists of the column name and the value for the corresponding group (sap.ui.table.AnalyticalColumn, property: groupHeaderFormatter). Several grouping levels are possible.

The corresponding column can be hidden to avoid duplicates (sap.ui.table.AnalyticalColumn, property: showIfGrouped). Exercise caution when using this option since hiding the column changes the table layout and may lead to confusion.

Group headers and the corresponding columns are shown – The relevant data is duplicated

Group headers shown, the corresponding column hidden – No duplicates

Aggregation

The column header menu can provide the option to show or hide aggregation totals for this column.

Intermediate aggregations are shown at group level for the corresponding columns if the group contains more than one line item (sap.ui.table.AnalyticalColumn, property: summed).

The overall aggregation is shown in a row at the bottom of the analytical table when the column contains values for a single unit of measure.

Overall aggregation for a single unit of measure

When the column contains values for more than one unit of measure, a Show Details link is displayed in a row at the bottom of the table, for example, when the column contains multiple currencies.

The Show Details link opens a popover that lists the totals for each unit of measure.

Overall aggregation for multiple units of measure via the 'Show Details' link

Freeze Columns

The column header menu can provide the option to freeze columns (sap.ui.table.AnalyticalTable, property: enableColumnFreeze). Selecting Freeze freezes all columns up to the one in which the operation was triggered (sap.ui.table.AnalyticalTable, property: fixedColumnCount).

When Freeze is triggered, the menu item changes to Unfreeze for the corresponding column.

Freeze setting in column header menu

Line Item Level

A line item contains a set of cells and provides options for selecting the item.

To prevent adverse side effects when scrolling vertically, all line items must have the same height.

(sap.ui.table.AnalyticalTable, property: rowHeight)

Line item

Drag and Drop

One or several items can be moved to other UI elements using drag and drop operations (sap.ui.table.AnalyticalTable, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop

Whole item as drop target

Cell Level

A cell provides one data point.

It can contain one of the following controls to display this data point:

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 with alignment, condensed mode, screen reader support, and keyboard support.

If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false). Do not wrap.

Cell

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows (like group headers). Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

By default, the analytical table provides a context menu on the group headers (for example, Expand, Collapse, …). Otherwise, no default context menus are provided.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or Shift+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Analytical table with context menu

Guidelines

Data Density vs. Complexity

The analytical table can be used to display and work with large amounts of data. Unfortunately, the analytical table has a high data density and therefore conveys an immediate feeling of complexity.

Only show tables with a lot of data as a last resort. To make the data easier to read, you should instead try the following:

Break down the data into manageable chunks and allow the user to navigate or drill down between them.
Use charts with drilldown functionality until the amount of data is more manageable.

Try to avoid horizontal scrolling in the default delivery.

Try to minimize the number of columns, especially if there is a large number of rows.

Table Title

Implement the table title by using a title control in a toolbar.

Use a table title only if the title of the table is not indicated in the surrounding area.

Do not use a table title if it simply repeats text that is already above the table. For example:

A pricing conditions table is the only control on a tab labeled Pricing Conditions.
A section or subsection on an object page contains only one table.

Use a table title if you need the item count, table toolbar, or variant management. To avoid repeating text, feel free to use generic text as a table title, such as Items.
Exception: If the surrounding area contains the table title, and both the item count and toolbar can be added to the surrounding area, no additional table title is needed.
Example: An object page (sub-)section contains only one table. In this case, add the item count and the table toolbar to the (sub-)section header.

If you use a table title, show either a title for the table, with or without variant management, or an item count in the following format:

Items (2,534).

The item count in the table title includes all the visible items that a user can reach by scrolling or expanding groups. Group headers are not included.

Remove the item count in the table title if there are zero items.

Developer Hint

Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table.

If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

Selection

Single Selection

For single-selection 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).
When setting a limit, also display the corresponding message when the user selects more items at once than the limit allows (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification).

In multiple selection mode (multi toggle), do not show checkboxes in the first data column in the default delivery to avoid confusion.

Don't

Do not add checkboxes to the first column

Never disable the selection checkbox. If an action can’t be performed on a specific item, inform the user after the corresponding action has been triggered. For more information, see Enabling/Disabling Actions.

Loading Data

To indicate that the table is currently loading items, use the busy state (sap.ui.table.AnalyticalTable, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Errors and Warnings

To indicate that the table contains items with errors or warnings, show a message strip above the table. On the message strip, provide information about errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

To indicate an error in a single row, see Item States below.

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

Developer Hint

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

Table containing errors and warnings

Columns – Best Practices

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

By default, the analytical table assigns the same width to each column. We recommend overwriting this default to provide optimal space for your content (sap.ui.table.AnalyticalColumn, property: width).

If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the size of the browser window results in a scrollbar. If the user resizes a column, and the total width of all columns exceeds the table width, a scrollbar appears. If the columns do not take up the full table width, white space appears to the right of the last column.

If you define the column width as a percentage, resizing one column affects the width of several or all columns. Reducing the size of the browser window truncates the texts. This ensures that the columns fill up all the available space. A scrollbar appears only if width of all the columns still exceeds the table width after the automatic width adjustments. To avoid the side effect of undersized columns, you can set a minimum width per column. However, this this minimum width is only taken into account if columns are automatically resized. End users can still reduce the column width to below the defined minimum (sap.ui.table.Column, properties: width, minWidth).

If you set the column width to “auto”, the behavior is the same as for “percentage”. However, unlike “percentage”, “auto” distributes the columns equally.

To decide on how to set the column width (pixel/rem/em vs. percent/auto), keep the following in mind:

For tables with only 2 to 3 columns, use pixel-based units. This ensures that the values in the columns are not spread over the whole screen on wide screens, which improves the readability of the line items.
For tables with many columns, where a horizontal scrollbar is usually needed, use pixel based units. This avoids unintended side effects when resizing columns.
For all other tables, use whatever fits your case better.

Be cautious when mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it can also cause even more side effects when resizing a column. If you are using percentage-based widths for one or more columns, consider not allowing end users to resize columns at all.

Optimize the column width for its initial visible content, including the column header texts. If this is not possible (for example, if showing the full texts would result in extremely wide columns), let the texts truncate. End users can change the width of the column to read the full text, as needed.

Maintain a constant column width and avoid adjusting it automatically when the content changes.

Always keep to one line of text. Do not wrap.

Don't

Don't truncate the initial visible content In the default delivery

Don't

Never wrap texts

Column Headers – Best Practices

For each column, provide a label in the column header. In the default delivery, do not truncate the column header texts. Only let the text truncate if showing the full text would make the column too wide. Never wrap the text.

Content Alignment

For alignment of cell content, follow the guidelines below.

Left-align: text, IDs, phone numbers, URLs, passwords, and email addresses.

Left-alignment of text

Right-align: numbers, except IDs, to ensure comparability of numbers and amounts.

Right-alignment of numbers

Right-align amounts with currencies to the cell and align their respective decimal points.

This ensures that amounts with different currencies are shown correctly, regardless of whether the currencies have 0, 2, or 3 decimals.

For aligning to the decimal point, use the sap.ui.uinified.Currency control.

Alignment to the decimal point

Right-align dates and times.

This ensures comparability for most formats and locales.

Right-alignment of dates

Left-align status information.

Left-align status information

Center-align icons.

Left-align micro charts.

XS micro charts in condensed mode

Content Formatting

Key Identifier

Use a bold label or an emphasized link as the key identifier of an item. In the default delivery, show the key identifier in the first column.

Emphasized link

For strings with IDs, use one of the following:

Show the ID in a separate column. Use this format if users need to sort, group, or filter by both the string and the ID.
Show the ID in parentheses after the corresponding string. In this case, you must opt for one criterion for sorting, filtering, and grouping – either the string or the ID. This option is then used for all sort, filter and group actions and can’t be changed later by the user. Use this format only if users don’t need to sort, filter, and group by both the string and the ID.

Text and ID in two columns – Allows sorting, filtering, and grouping for both

If displayed as a link, use only the string as the link, not the ID

Text and ID in one column – Sorting, filtering, and grouping are available for either the text or the ID, but not for both

If displayed as a link, use the whole text as the link

Truncation

Avoid truncation of typical content in the default delivery (sap.ui.table.AnalyticalColumn, property: width). However, since the columns are resizable, do not worry too much if truncation occurs as columns can still be enlarged if necessary.

To prevent adverse side effects when scrolling vertically, all line items must also have the same height. If you need to decide between truncation and different row heights, choose truncation. Do not wrap.

Optimize column width for typical content, not all content

Number of Links

Are there too many links? Use subtle links to avoid a wall of links. Standard links are also emphasized more if they are surrounded by subtle links.

For example, a financial table consists of several columns with summarized cells. A summarized cell shows the total sum of several database entries. Each sum should be a link to a report that shows details about which database entries produce the total sum. The line item identifier should also be a link that provides more detail about the line item itself. Use a standard or emphasized link for the item identifier, and subtle links for the summarized cells.

Emphasized links, links, subtle links, and text

Missing Value

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

Leave empty fields blank

Numbering Items

In terms of numbering items:

If the item number is more like an ID with regard to its description, use ID formatting as described above.
In all other cases, use a separate column for the item number.

Add a separate column for the item number

Status

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

For status information on text, use an object status.

Semantic colors on text

Micro Charts

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

Micro charts in an analytical table

Empty Tables

Avoid empty analytical tables. If necessary, provide instructions on how to fill the analytical table with data (sap.ui.table.AnalyticalTable, properties: noDataText, showNoData).

Examples:

If a table is initially empty, provide at least a basic text:
No items available.
Overwrite this whenever a hint can be provided on how to fill the table with data.
If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
To start, set the relevant filters.
If a table is used together with a filter bar and the filter does not return results, use the following text:
No data found. Try adjusting the filter settings.

Adapt the texts above if:

The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
The standard text is misleading (for example, if the data is filled based on a list-detail pattern instead of filter settings).

Provide meaningful instructions

Invalid State

To show an invalid state of the analytical table within the list report floorplan, show an overlay on the analytical table and the corresponding toolbar (sap.ui.table.AnalyticalTable, property: showOverlay). The overlay prevents user interactions.

Use this within the list report floorplan if filter settings have been changed but the analytical table has not yet been updated.

Analytical table with invalid data

Item States

To show that an item has been modified, for example, within the global edit flow, add the string (Modified) in an additional column with the label Editing Status.

In the default delivery, add a column directly behind the key identifier.

A modified item

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.

A modified item with an error

To show that an item is locked, add a transparent-style button with the corresponding icon and the text Locked by [name] in the Editing Status column.

A locked item

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

Item in draft state

Show only one state at a time.

Numbers and Units

Show the unit of measurement in one of the following ways:

The number and unit are in the same cell. Do this if sorting, filtering, or grouping by the unit of measurement are not needed.

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

Number and unit of measurement in one cell

The number and unit are in separate columns. Do this if sorting, filtering, or grouping by the unit of measurement are a common use case.

Note that this column can be hidden or moved independently of the column containing the corresponding number. Therefore, be sure to have clear labels for both columns to communicate the dependency.

Number and unit of measurement in two columns

If the unit of measurement is the same for all rows, show the unit of measurement in the column header. Otherwise, show the unit of measurement within the row.

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items. These are keyboard operable and available on all browsers.

Use drag and drop only in addition to existing visible UI elements

Do not use drag and drop for rearranging items in the analytical table. The analytical table is mainly used for grouping items and for calculating the totals per group and column. Moving items to another group also means that a value of the dropped item changes: because grouping is based on values in a column, the dropped item needs to take on the value of the target group for the corresponding column.

Example:
A table is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. Because changing the value in this way doesn’t make sense, rearranging items is not permitted in analytical tables.

Don't

Do not use drag and drop for rearranging items in the analytical table

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar). Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

The context menu can be triggered for the table, row, or cell. However, we do not recommend using context menus for cells: because the content of a cell is a different touch target than the cell itself, opening a cell context menu via touch is quite hard, even in cozy mode.

Do not combine context menus with condensed mode: editable controls fill the entire space inside a cell. Because of this, context menus cannot be opened at all with touch or mouse interaction.

Actions

Multiple Items

To trigger actions on multiple items, use a multiselection analytical table (sap.ui.table.AnalyticalTable, property: selectionMode, value: MultiToggle). Offer the corresponding actions in the table toolbar.

Do not offer action triggering on multiple items if the table is generally expected to have fewer than 10 items. In this case, try to use the responsive table instead of the analytical table.

Single Item

To trigger actions on a single item (sap.ui.table.AnalyticalTable, property: selectionMode, value: Single):

Show the actions on the table toolbar.
In rare cases, show the actions within the line item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. Provide a separate column per action. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

Single Cell

To trigger actions on a single cell, create the corresponding click event. Do not use the cell click event if the cell contains interactive controls, such as links.

To trigger navigation on line item level choose one of the following options:

Use a link for the attribute that identifies the row. Clicking the link triggers the navigation.
Add the RowActions column and show the navigation indicator ( ) at the end of the row. The navigation arrow triggers the navigation.

Special case: Multi-selection in a 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.

Navigate to details page

Single Cell

For triggering actions on a single cell, create the corresponding click event. Do not use the cell click event if the cell contains interactive controls, such as links.

Add Items

To let users add items, place an Add or Create text button on the table toolbar.

Use Create if the button adds a brand new item that doesn’t yet exist on the database.
Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the table, with a visual highlight at the beginning of the row.

Enable the shortcut Ctrl+Enter (and ideally also Enter) to trigger the Add or Create button.

There are three options for adding an item. In order of priority (most recommended first), these are:

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.
Open a dialog for larger tables with up to 8 editable columns. Save the new item at the dialog level.
Navigate to a new page. Only use this option for very complex scenarios that cannot be handled by a dialog (for example, tables with more than 8 columns). When the user presses Save in the footer toolbar of the create page, navigate back to the table.

Depending on the flow, an item can be in one of three different states:

New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item in the table. Ignore current sort, filter and grouping criteria to keep the item visible.
Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is applied as follows:
- Inline creation: After Save is triggered on the table toolbar or at page level.
- Create with dialog: A table showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

If draft handling is used, new items are not saved at table level, but rather with the entire draft.

For more details, see the guidelines for managing objects (including subarticles).

Editable Content

For editable content, only use the following controls, and only one control per cell:

Only these controls are optimized for all viewing modes of the analytical table.

If you need edit mode, change your text controls, such as label, text, link, object status, icons, and currencies, to editable controls as soon as you switch to edit mode, but not before. You can do this by exchanging the controls, for example, from sap.m.Text to sap.m.Input.

For mass editing items:

Provide multiselection.
Provide an Edit button.
If several items are selected, clicking the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

This is similar to mass editing in the split-screen layout floorplan.

Warning

Do not offer editing for summarized cells. A summarized cell shows the total sum of several database entries. Changing the total sum does not make sense since it is unclear how this sum is divided between the different database entries.

Interactive controls – Inline

View Settings

There are several ways to show Sort, Filter, and/or Group settings:

Column header menu: In all cases, show the corresponding settings in the column header menu.
View settings dialog: Simple and more flexible with regard to filter settings. No advantage for sorting. Allows the user to ungroup grouped columns.tables with a medium amount of items.
Table personalization dialog: Provides complex options for sorting items by several levels and allows the user to ungroup grouped columns. It also provides a query-builder-like approach for filter settings. The complexity of the options is also its downside. Use the table personalization dialog for tables with a large number of items.
If filtering is a main use case, use the filter bar. In this case, avoid offering additional filter settings on the table. If you do, the filter settings on the table work only on the result set provided by the filter bar.

Always be careful when synchronizing the settings in the dialog with the settings from the column header menu.

Trigger the dialogs in one of the following ways:

View settings dialog: Provide several buttons, one for each of these view settings. Each button opens the view settings dialog on the corresponding page.
Table personalization dialog: Provide a settings button, which opens the table personalization dialog containing all pages.

Use only the view settings you really need. For example, do not offer grouping if it does not support your use case.

Column header menu with view settings

Table toolbar with triggers for view settings dialog

Table toolbar with trigger for table personalization dialog

Persist the view settings. When a user reopens the app, show the analytical table with the same sort, filter, group, and aggregation settings as last defined by this user.

Sort

Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the first column in the default delivery.

To display the current sort state, an icon is shown in the column header of the last sorted column. This icon indicates the sort direction (sap.ui.table.AnalyticalColumn, properties: sorted, sortOrder, sortProperty).

For the default sort setting, sort by the column that identifies the row, which is usually the first column in default delivery. Use a meaningful sort order, such as alphabetical order for text, numeric order for numbers, or chronological order for dates.

Column, sorted ascending

Column, sorted descending

The descending sort order must always be the exact reverse of the ascending sort order.

For each column, provide a meaningful sort order. For example:

Sort text alphabetically
Sort numbers by their value
Sort status information by the severity of the status:
- Ascending: Sort status information from positive to negative, with neutral last.
- Descending: Sort status information from negative to positive, with neutral first.

Object status sorted ascending, with neutral status last

Object status sorted descending, with neutral status first

- Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
- Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Object status sorted ascending and alphabetically, from positive to negative with neutral last

Object status sorted descending and alphabetically, from negative to positive with neutral first

Filter

To display the current filter state, an icon is shown in the column header of the filtered column (sap.ui.table.AnalyticalColumn, properties: filtered, filterProperty, filterValue, filterOperator, defaultFilterOperator, filterType).

Column, filtered

Group

To display the current group state, group headers are shown. Show the following text in the group header (sap.ui.table.AnalyticalColumn, properties: grouped, showIfGrouped, groupHeaderFormatter):

[Label of the grouped column]: [Grouping value]

If there is no grouping value, show the following text:
[Label of the grouped column]: (Not Available)

This is the case if you have a group of items that don’t have a value for the grouped column.

Set the property collapseRecursive to “false” to keep subgroups expanded even after collapsing and expanding the parent group.

Group headers, several levels

On non-touch devices, right-clicking a group header opens the group header menu. On touch devices, the same menu is opened by using the menu icon on the right side of a group header.

The group header menu provides several options:

Show/Hide: Shows or hides the column in the table layout, although it is grouped.
Ungroup: When the user ungroups a column, the corresponding group headers disappear. If the column was hidden, it is shown again as a separate column.
Ungroup All: The columns are shown again.
Move Up: Rearranges the grouping levels hierarchy by moving the selected group above the group that is one level higher up in the hierarchy.
Move Down: Rearranges the grouping levels hierarchy by moving the selected group below the group that is one level lower down in the hierarchy.
Collapse Level: Collapses all groups on the corresponding grouping level.
Collapse All: All groups are collapsed.

Group header menu

Group header on touch devices

In general:

Offer grouping on objects and attributes.
Do not offer grouping on measures.
If appropriate, offer reasonable grouping by default, but do not exaggerate. As a rule of thumb, use up to three group levels.
Provide more space for the first column. Grouping needs an indent per group level. Extra space in the first column prevents truncated text.

Aggregate

To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.

If items are grouped, an intermediate sum is shown:

At the bottom of each group if the group is expanded.
In the group header if the group is collapsed.

(sap.ui.table.AnalyticalColumn, property: summed)

When aggregating amounts with different units of measurement, show an asterisk (*) in the aggregation rows.

When sorting an aggregated column, only the leaf nodes of a group are included by default. If each measure column currently displays a single unit of measurement, the order of the groups can also be affected.

For example:
Let’s assume that table items are grouped by Country/Region and aggregated by Total Net Amount. If you sort the Total Net Amount column in descending order, the largest total net amount is shown first.

Warning

Only enable sorting by totals if each column has a single unit of measurement. This prevents inconsistencies in the sorting behavior, which depends on user settings, such as filter settings or the columns currently displayed.

Developer Hint

To allow sorting by totals, the following conditions must be met:

For each measure column, multiple units must not occur in the displayed data, regardless of whether or not totals are shown.
The autoExpandMode of the AnalyticalBinding must be set to Sequential. Note that the default is Bundled.

In general:

Offer aggregation on measures, but not on objects or attributes.
Avoid aggregations on the first three columns for the default delivery. As soon as grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.
Where appropriate, offer reasonable aggregation by default.

Aggregation and groups

Personalization

Only offer personalization if you need more columns than a tablet screen can display at any one time, which is usually five.

Persist the column layout. When a user reopens the app, show the analytical table with the same column layout settings as last defined by this user.

Add, Remove, and Rearrange Columns

To add, remove, or rearrange columns, use one of the following:

The table personalization dialog: It offers some simple settings for column layout. Use this if you have only a few columns to choose from and/or you use the view settings dialog.
The p13n dialog: Besides various complex view settings, it also provides settings for column layout. Use this if you have a large number of columns to choose from and/or you use this dialog anyway for view settings.

In both cases, trigger the dialog via the settings button in the table toolbar. As short cut, use CTRL+COMMA.

You can also use drag and drop to rearrange columns (sap.ui.table.Table, property: enableColumnReordering). If you allow rearranging via drag and drop as well as via a dialog, keep both places in sync.

Resize Columns

Resizing columns works differently on touch and non-touch devices.

Non-touch devices: Drag and drop the column separator on the right side of the column. Double-clicking the column separator optimizes the width of the column for the data currently loaded into the front end, which is usually about 100 rows.
Touch devices: Clicking the column header reveals two buttons: one for opening the column header menu, another one for resizing the column. Drag and drop this second button to resize the column.

Freeze Columns

For freezing columns, offer the setting in the column header menu (sap.ui.table.AnalyticalTable, property: enableColumnFreeze).

Selecting Freeze on a column freezes all columns from the first one to the one where Freeze is selected. On this column, the menu entry changes from Freeze to Unfreeze.

Frozen column

Highlight Items

To show that an item needs attention, you can display a highlight indicator in front of the item. The highlight indicator can be used to indicate:

A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.ui.table.AnalyticalTable, aggregation: rowSettingsTemplate)

Highlighted items

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.

'Export to Spreadsheet' menu button

Properties

sap.ui.table.AnalyticalTable

The following additional properties are available for the analytical table:

The property: width defines the width of the analytical table.
The property: rowHeight defines the height of each row in the analytical table. Since the height required is calculated automatically by the analytical table, this property is only needed rarely.
The property: columnHeaderHeight defines the height of the column headers. Since the height required is calculated automatically by the analytical table, this property is only needed rarely.
The property: columnHeaderVisible can be used to hide the column headers. Always show the column headers.
The property: showColumnVisibilityMenu provides an additional entry in the column header menu that allows columns to be shown or hidden. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
The property: columnVisibilityMenuSorter is used for sorting the columns inside the column header menu if showing and hiding columns is provided in the menu. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
The property: visibleRowCount defines the height of the analytical table. Show as many rows as fit on the screen.
The property: visibleRowCountMode defines whether the height of the analytical table is fixed or automatically calculated based on the space provided by the underlying container. For automatic calculation, make sure that all rows have the same height.
The property: minimumAutoRowCount defines the minimum number of rows that must be shown if the property: visibleRowCountMode is set to “auto”. Show at least three to five rows.
The property: firstVisibleRow defines the first row shown in the visible area of the analytical table. The analytical table is scrolled accordingly.
The property: allowColumnReordering is deprecated. Use the property: enableColumnReordering instead.
The property: editable does not have a visible effect. Please do not use it.
The property: threshold is used for optimizing lazy loading of items. In most cases, the default value is appropriate.
The property: enableGrouping is experimental and does not have a meaningful effect on the analytical table. Do not use it.
The property: sumOnTop shows additional aggregation values on the group header, even if the group is expanded. Do not use it.
The property: enableCustomFilter changes the filter entry in the column header menu from an edit box to Filter…. Selecting this entry throws an event that apps can react to, for example, by opening a dialog. In general, you should choose the built-in filter over your own implementation. Specifically, keep filtering via the column header menu simple, while offering more advanced options via the table personalization dialog.
The property: enableBusyIndicator has not yet been fully implemented. Do not use it.
The property: title adds a line of text on top of the analytical table. Do not use it. To add a title to the table, use a toolbar.
The property: footer adds a short text at the bottom of the table.
The property: Busy sets the analytical table to busy state. While in busy state, the whole table cannot be used and items cannot be read due to an overlay.
The property: Tooltip does not have an effect. Do not use it.
The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). Do not use it.

sap.ui.table.AnalyticalColumn

The following additional properties are available for the analytical column:

The property: leadingProperty is used for data binding.
The property: inResult is used for data binding.
The property: visible defines whether a column is shown or hidden.
The property: name defines the name shown in the column header menu for showing and hiding columns. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Please do not use this property.
The property: headerSpan defines whether one column header is used for one or several columns. To prevent adverse side effects, always use one column header for only one single column. Please do not use this property.
The property: Tooltip does not have an effect. Please do not use it.

Resources

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

Elements and Controls

Bullet Micro Chart (guidelines)
Comparison Micro Chart (guidelines)
Feed List Item (guidelines)
Grid Table (guidelines)
Link (guidelines)
List Report Floorplan (guidelines)
Multi-Input Field (guidelines)
Responsive Table (guidelines)
Stacked Bar Micro Chart (guidelines)
Table Personalization Dialog (guidelines)
Table Toolbar (guidelines)
Tree Table (guidelines)
Variant Management (guidelines)
View Settings Dialog (guidelines)

Implementation

Analytical Table (SAPUI5 API reference)
Analytical Column (SAPUI5 API reference)
Analytical Column Menu (SAPUI5 API reference)

Smart Table

Intro

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

When to Use

Use the smart table if:

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

Do not use the smart table if:

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

Components

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

The components of a smart table

Table Toolbar

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

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

Title
Item counter
Variant management
Show Details / Hide Details
View Settings
Export to Spreadsheet
Maximize / Minimize

In addition, you can add app-specific actions.

Title

Displaying a title is optional (property: header).

Guidelines

Add a title whenever the title is not indicated in the surrounding area.
If you don’t display a title, ensure that you still provide a table title for screen reader users.

Developer Hint

If there is no title title, support screen reader users as follows: create a simple table in the XML view, use ariaLabelledBy to point to the corresponding text, and add this table to the smart table. Make sure that the table type within the smart table is set accordingly. The smart table will take care of the rest (creating columns, and so on).

Item Counter

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

Guidelines

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

You expect this to cause performance problems.
You use a responsive table and use the More button for loading additional items. Use the item counter on the More button instead.

Variant Management

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

Guidelines

Use variant management only if really needed.

Show Details / Hide Details

The Show Details / Hide Details button is mandatory with and only available for the responsive table. Columns with a low priority (low or medium priority on phones) are hidden in the pop-in area (properties: demandPopin, enableAutoColumnWidth, showDetailsButton, annotation: UI.Importance).

You can define which priority levels cause the columns to be hidden (property: detailsButtonSettings). The button only appears if there are columns that belong in the pop-in area. Columns disappear from right to left but columns with the priority “High”, are never hidden. They are shown in the pop-in area if they do not fit on the current screen size

Details hidden

Details shown

View Settings

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

Guidelines

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

Sort and Filter

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

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

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

Guidelines

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

Developer Hint

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

Group

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

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

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

Guidelines

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

Column Settings

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

Guidelines

If sorting, grouping, and/or filtering are needed, also show the column settings (sap.ui.comp.smarttable.SmartTable, property: useTablePersonalisation).

Developer Hint

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

Export to Spreadsheet

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

Guidelines

Only offer the Export to Spreadsheet option if your end users typically export the data shown in the table to work with it in a spreadsheet application.
- This is usually the case if data is collected from several systems and analyzed in the spreadsheet application.
- This is not usually the case for worklists, attachment lists, tables with only a few items, shopping carts, or data that does not need to be analyzed.
If you offer the Export to Spreadsheet button, use the front-end export.
If your table has columns with non-textual content, provide a textual equivalent for those columns. Non-textual content is not exported.

Warning

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

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

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

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

Maximize / Minimize

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

Guidelines

Use Maximize / Minimize only if really needed.

App-Specific Actions

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

Developer Hint

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality, such as a table title, item counter, variant management, view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).
If you are using a custom toolbar in a responsive table, show the bottom border of the toolbar. For all other tables, do not show it (property: style, value: clear).
The property placeToolbarInTable adds the toolbar to the corresponding aggregation of the inner SAPUI5 table. In most cases, set this to “true”, especially when you are using the custom toolbar with the responsive table. Otherwise, the table toolbar cannot stick to the top of the surrounding layout container.

Infobar

Infobar with filter information

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

Guidelines

For the responsive table, the info bar is mandatory.
For all other tables, do not show the info bar.

Table

Responsive table within a smart table

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

Table
Column Visibility
Column Layout
Column Headers
Column Content

Table

The table provides the following features:

You can use the responsive table, grid table, tree table, or analytical table within the smart table (property: tableType).

Guidelines

The analytical table, tree table and grid table are not fully responsive. They are available only for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
For the responsive table, the smart table initially loads 20 items and shows a More button for loading additional items. Change this behavior if:
- You expect fewer than 200 items. Load all items from the start (sap.m.Table, property: growing).
- You expect more than 200 items. Adapt the number of items initially loaded to cater for large screens, and load additional items automatically when the user scrolls down (sap.m.Table, property: growingScrolllToLoad).

Developer Hint

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

Developer Hint

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

While the grid table, analytical table, and tree table support multi-selection by default within the smart table, the responsive table does not offer any kind of selection. The selection mode can be changed.

Developer Hint

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

Column Visibility

Columns are created automatically. Items are rendered based on the properties and metadata of the underlying OData service (annotation: LineItem, properties: entitySet, tableBindingPath, initiallyVisibleFields, ignoreFields). A column is generated for each OData entity property.

Developer Hint

If a column needs to be in the model but should not be shown, you can hide it from both the table and the P13n dialog (property: ignoredFields, annotation: UI.Hidden).

Use this option if:

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

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

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

Developer Hint

Columns can be removed at runtime. This is useful if the same table is used for similar, but slightly different objects. For one of the objects, specific columns need to be shown, for others they must be hidden, and users must not be able to add them in the personalization settings (function: deactivateColumn).

You can define which columns are initially visible when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleFields).

Guidelines

Keep the number of initially visible columns to a minimum. Avoid pop-in behavior (responsive table) or horizontal scrolling (all other tables) on a tablet screen size in the default delivery (annotation: PresentationVariant/ LineItem).
Also keep the number of additional columns offered in the personalization settings to a minimum. You can use the P13n dialog to let users show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value: false).

For each column that is initially visible, the LineItem annotation includes a DataField record, which allows you to influence the content rendering of the smart table.
For columns that are initially invisible, the content rendering can also be influenced via the annotation DataFieldDefault.

Developer Hint

If the same column is defined via LineItem and via DataFieldDefault, LineItem wins.

Column Layout

A default column width can be calculated for each column based on the data type, the column label, the edit/read-only state, and the annotations: textArrangement, MaxLength for strings, Precision and Scale for numeric data (property: enableAutoColumnWidth).
The calculated width is between 3 rem and 20 rem. Apps can change this default width if needed (annotation: CSSDefaults).
If the combined width of all the columns is less than the width of the table, the remaining space stays empty.

Guidelines

Choose a column width that avoids truncation for the initial data and (if feasible) for the column header label. If the default column width doesn’t fit, change it.

Developer Hint

For the responsive table, enableAutoColumnWidth also applies the following changes:

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

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

Columns can be resized by dragging the column separator. If the combined width of all columns is less than the width of the table, the remaining space stays empty. The smart table provides column resizing automatically in the following cases:
- Grid table / tree table / analytical table: Column resizing is automatically enabled with the column settings.
- Responsive table: Column resizing is automatically enabled with the automatically calculated default column width.

Responsive table with automatically calculated column widths, resizing, and remaining space

If the automatically generated content does not fit for your use case, you can override the automatic behavior with your own column template.
You can also add further columns. This allows you to provide columns with app-specific or inline actions, columns which show calculated values (based on more than one OData entity property), or – for responsive tables – columns that show more than one control.

Developer Hint

To add or override columns (“custom columns”):

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

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

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

Column Headers

You can specify a column header text for each column (annotation: sap:label).
SAP S/4HANA Only:
Tooltips are available by default for smart table column headers.
In smart tables, texts that exceed the column width always truncate (see Column Layout). The tooltip allows users to read the full column header text without resizing.

Guidelines

Provide a column header text for each column. (annotation: sap:label).

The column headers contain the following settings:
- Sort Ascending, Sort Descending
- Filter: Opens the P13n Dialog. If this does not fit for your use case, exchange this menu item (property: enableCustomFilter)
- Group (only analytical table, only on dimension columns)
- Total (only analytical table, only on measure columns): This setting is not persisted (annotation: sap:aggregation-role, value: measure).
  If a column contains entries with different units of measurement, a Show Details link appears instead of the total. Clicking the link opens a popover showing the subtotals per unit of measurement.
- Freeze (only available for grid table, tree table, and analytical table): Must be added manually.

Guidelines

Offer column totals by default for all columns where totals make sense (annotation: PresentationVariant).

Developer Hint

To add a Freeze option manually, declare the corresponding table inside the smart table in the XML view, and use the corresponding settings for this inner table.

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

Column header menu for a dimension column of an analytical table within a smart table

Column header menu for a measure column of an analytical table within a smart table

Content

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

You can render the smart table in either read-only or edit mode (with no option to switch), or allow users to switch between the two modes (properties: editable, useSmartToggle).
In read-only or edit mode, the smart table renders the controls as listed in the table below, or uses the smart field for both modes. If you use smart fields together with the option to switch between read-only and edit mode, the smart table renders the read-only controls as in the list below, but uses the smart field for edit mode. The smart field limits the rendering options (aggregation: customData, key: useSmartField), but also allows for:
- Better control of the visibility of a field per row (smart field, annotation: FieldControl)
- Use of value help for input fields

Developer Hint

From a performance perspective, using the smart field is more expensive than using the controls provided by the smart table directly. With this in mind, follow the rules below:

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

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

	Read-only	Edit	Annotations / Edm type	Comment
Static text	Text	Input field	Edm.String
Decimal numbers	Text	Input field	Precision, Scale, Edm.Byte, Edm.Decimal, Edm.Double, Edm.Int16, Edm.Int32, Edm.Int64, Edm.SByte, Edm.Single
Status information	Object status or Icon	Input field	Criticality, CriticalityType, CriticalityRepresentationType	Do not use editable status information.
Key identifier	Object identifier (responsive table) Text (all other tables)	Input field for the ID	SemanticKey, Common.EditableFieldFor
Text and ID	Text, object status, or object identifier	Input field for the ID	TextArrangement	Use together with the annotation mentioned above for static text, status information, or key identifier. Sorting, filtering, and grouping only works for the ID, even if the ID is not displayed.
Links with/without quick view	Smart link	Smart link	SemanticObject	Smart links can be customized using the aggregation: `semanticObjectController`
Dates	Text	Date picker	Edm.DateTime, sap:display-format, value: date, IsCalendarDate
Dates and times	Text	Date/time picker	Edm.DateTime, Edm.DateTimeOffset
Times	Text	Time picker	Edm.Time
Fiscal periods	Text	Input field	IsFiscalYear, IsFiscalPeriod, IsFiscalYearPeriod, IsFiscalQuarter, IsFiscalYearQuarter, IsFiscalWeek, IsFiscalYearWeek, IsDayOfFiscalYear
Amounts with currencies	Two text controls	Input field for the amount	sap:semantics, value: currency-code	In edit mode, the currency is shown as static text next to the input field.
Phone numbers	Link	Input field	IsPhoneNumber	Opens the system application for making phone calls.
Email	Link	Input field	IsEmailAddress	Opens the system application for writing emails.
Pictures	Image	Input field	IsImageURL	Only available for the responsive table. In edit mode, the input field contains the URL to the image.
Boolean	Text	Checkbox	Edm.Boolean	For read-only, the displayed text is Yes or No.

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

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

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

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

Guidelines

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

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

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, export to spreadsheet, and P13n dialog (see the corresponding articles for details.) Note that the smart table provides limited options and not all settings of the underlying controls are available.

Empty Tables

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

If a table is initially empty:
No items available.
Overwrite this whenever a hint can be provided on how to fill the table with data.
(property: initialNoDataText, value: $NO_FILTERBAR)
If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
To start, set the relevant filters.
(property: initialNoDataText, value: $FILTERBAR)
If a table is used together with a filter bar and the filter does not return results, use the following text:
No data found. Try adjusting the filter settings.
(aggregation: noData, changeable at runtime)
If the user has hidden all of the columns in the personalization settings, the following text is shown:
Right now, there are no visible columns in the table. Please select the columns you need in the table settings.
This text cannot be changed.

Guidelines

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

An empty smart table

Errors and Warnings

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

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

Table containing warnings

Table containing errors and warnings

Guidelines

To show that an item contains an error,

Highlight the row accordingly.
Add the string (contains errors) and place it at the bottom of the column that identifies the line item (responsive table) or in the Editing Status column (all other tables).

Developer Hint

Binding-related messages are shown automatically.

Responsiveness

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

Toolbar Overview
Infobar
Responsive Table via auto pop-in mode
(sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true).
You can use the UI.Importance annotation to influence the priority of each column.
You can provide a Show Details button to let users show/hide columns with low importance (property: showDetailsButton).
Grid Table, Tree Table, Analytical Table are not fully responsive. They are available only for desktops and tablets. For smartphones, you need to take an adaptive approach by offering an additional UI.

Guidelines

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true). Ensure that the most important columns stay in the tabular layout as long as possible (annotation: UI.Importance). The most important columns are those that contain the following information:

The column that identifies the line item.
The column that contains the key attribute.

Developer Hint

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

Examples

Responsive table within a smart table

Grid table within a smart table

Top Tips

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

Properties

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

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

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.

Tree table shown on a desktop

Tree table shown on a tablet

Types

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

For a desktop, you can also display even more rows on the same screen height by adding the condensed mode in addition to the compact mode. This renders less white space for each item.

Note that the condensed content density has always to be set in addition to compact. Do not use condensed on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable and / or unwanted results, e.g. cozy sized controls in condensed sized containers, missing paddings, etc.

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

Furthermore, condensed mode is not available for Internet Explorer 9. If condensed mode is to be used, please provide a fallback.

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

Compact Mode

Tree table – Compact mode

Condensed Mode

Tree table – Condensed mode

Components

Column Header

The column header provides the label for the corresponding column and access to the column header menu.

Resizing columns works in the following ways:

Mouse interaction: Dragging the separator line between two columns (sap.ui.table. Column, property: Resizable). Double-clicking optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable).
Touch interaction: The user taps the column header to reveal two buttons: one for showing the column header menu and one for resizing. Drag the latter to resize the column.
Keyboard interaction: The width of the focused column header can be increased with Shift+Right and decreased with Shift+Left.

After resizing a column, the adaptation of the column widths depends on how the column width is set:

If column widths are set in pixel-based units (px, em, rem), the corresponding column is adapted and following columns are moved accordingly. The width of all other columns is not affected.
If all the columns together take up less width than the table control, an empty space is added. If all the columns together take up more width than the table control, a scrollbar appears.
If all column widths are set in percentage or “auto”, resizing one column might also lead to the automatic resizing of some or all other columns. The position of the resized column might also be affected. This is done to ensure that the whole table width is used and no white space is added. A scrollbar appears only, if all or most of the columns get very small. To avoid the unintended side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

Columns can be rearranged by dragging the column header to another position (sap.ui.table.TreeTable, property: enableColumnReordering). Keyboard: the focused column header can be moved by one position to the corresponding direction with Shift+Left / Shift+Right.

Tree table – Column header

Opening the column header menu on touch devices

Fewer columns than space available

Line Item

A line item contains a set of cells and provides options for selecting the item.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.TreeTable, property: rowHeight).

Tree table – Line item

In rare cases, show the actions within the line item. One example would be an Add to Cart button in a shopping application. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. Provide a separate column per action. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.

Tree Column

The first colum (tree column) provides the hierarchical structure.

Tree table – Tree column

Expand/Collapse Button

The expand/collapse button is offered on container nodes to allow the child items of the corresponding container to be shown or hidden.

Tree table – Collapse

Tree table – Expand

Container Node

A container node is a line item that contains child elements.

Tree table – Container node

Leaf Node

A leaf node is a line item that does not contain child elements.

Tree table – Leaf node

Cell

Each cell provides one data point. It can contain one of the following controls to display the data point:

Text
Label
Object status
Icon
Button
Input field
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).

Tree table – Cell

Tree Cell

A tree cell is a cell inside the tree column. Besides its data point, it provides a collapse/expand button on container nodes, and it indents the different hierarchy levels.

Tree table – Tree cell

Column Header Menu

For the tree column, the column header menu can contain the menu item Freeze and a Filter field, in which the user enters free text.
For all other columns, only the free text filter is available.

Tree table – Tree column header menu

Selection Cells

For multiselection tree tables, the first column contains checkboxes for selecting line items. Besides multiselection, the tree table offers a single-selection mode and also a read-only mode, in which line items are not selectable.

Tree table – Selection cells

Select All

For multiselection tree tables, the column header can contain a checkbox above the selection cells for selecting or deselecting all line items.

Tree table – Select all

Scrollbar

The tree table allows horizontal and vertical scrolling. You can add any number of line items to the tree table, which uses “lazy loading”.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.TreeTable, property: rowHeight).

The tree table is optimized to allow faster scrolling within the first 1000 items.

Tree table – Vertical scrollbar

Behavior and Interaction

Selection

The tree provides the following possibilities:

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

Tree table – No selection

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

Tree table – Single selection

Multiple selection: One or more items can be selected. The tree table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back. The Shift key can be used to select a range.

For multiple selection, you can choose between two variants.

Multi-toggle mode (property: selectionMode = MultiToggle)
Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)

These variants behave differently when the user selects more items than are currently loaded in the front end.

Multi-toggle

In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end (keyboard: Ctrl+A). All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

Multi-selection plug-in

If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:

By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
- The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and a message can appear (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
- If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets (Keyboard: Ctrl+A).
If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.

Information

When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.TreeTable, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

Tree table – Multiple selection

Multi-selection plug-in with a limit

Selection Behavior

An item can be selected in different ways, depending on the configuration of the tree table (sap.ui.table.Table, property: selectionBehavior):

Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection tree tables if clicking a row or a cell is not used for anything else.
RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection tree tables if clicking a row or a cell is not used for another purpose, such as navigation.

Set the property collapseRecursive to “false” in order to keep the selection on subnodes even after collapsing and expanding the root node.

Drag and Drop

One or several items can be repositioned within a table or moved to other UI elements using drag and drop operations (sap.ui.table.TreeTable, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop

Column Header Menu

Sort

The column header menu can provide two sort options (sap.ui.table.Column, properties: sortProperty, showSortMenuEntry):

Sort Ascending
Sort Descending

The user selects one of these options to sort the corresponding column accordingly (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

Sort settings in column header menu

Filter

The column header menu can provide a search field for entering free text. If the user enters a term in the input field and triggers the search by pressing Enter, the tree is filtered by the tree column and the corresponding value. If no items match the filter values, the filtered tree table may be empty.

Tree table – Filter

Freeze Columns

The Freeze/Unfreeze option is provided in the column header menu of all columns. Using Freeze on one column freezes all columns from the first one to the selected one.

Tree table – Freeze

Column Handling

Show/Hide Columns

Columns can be shown and hidden. If the tree column is hidden, the following column is the tree column.

Rearrange Columns

The user rearranges columns by dragging and dropping the corresponding column header. The tree column is always the first column and cannot be dragged. Keyboard: the focused column header can be moved by one position to the corresponding direction with Ctrl+Left / Ctrl+Right.

Resize Columns

Columns are resized as follows:

Mouse interaction: The user drags the separator line between two columns (sap.ui.table. Column, property: Resizable). Double-clicking the line optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable). Note that auto-resizing works only if the cells in this column contain one of the following controls: text, label, link, or input.
Touch interaction: The user clicks or taps the column header to reveal two buttons: One to show the column header menu, and one for resizing. The user drags the latter to resize the column.
Keyboard interaction: The width of the focused column header can be increased with Shift+Right and decreased with Shift+Left.

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows (like group headers). Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or Shift+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Tree table with context menu

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.

Developer Hint

The tree table itself has no influence on the filter result. It sends a filter request and displays whatever comes back. Make sure that the result set is meaningful.

Sorting

First of all: Is sorting meaningful in your tree? If so, decide on a meaningful default sort order.

If sorting is meaningful, is it meaningful on all levels? Or does the tree structure need to be stable? In the latter case, sort only leaves, but not nodes.

Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the tree column.

To display the current sort state, an icon is shown in the column header of the most recently sorted column. This icon indicates the sort direction (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

The descending sort order must always be the exact reverse of the ascending sort order. For each column, provide a meaningful sort order. For example:

Sort text alphabetically
Sort numbers by their value
Sort status information by the severity of the status:
- Ascending: Sort status information from positive to negative, with neutral last.
- Descending: Sort status information from negative to positive, with neutral first.

- Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
- Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Loading Data

To indicate that the table is currently loading items, use the busy state (sap.ui.table.TreeTable, property: busy). Do not show any items or text. As soon as the data has been loaded, remove the busy state and show all items.

Initital Display

Think of the initial expand / collapse state of a tree: If your structure contains many items on the root level, it might make sense to collapse the whole tree in the beginning.

In contrast, if the main items to work with are displayed on a deeper level (e.g. the parent nodes are just some kind of categorization), the tree should be expanded up to the first level where the needed items appear.

Errors and Warnings

To indicate that the tree table contains items with errors or warnings, show a message strip above the tree table. On the message strip, provide information on errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

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

Developer Hint

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

Selection

We strongly recommend using the multi-selection plug-in. This ensures that all items selected using Select All or as part of a range are included – even if some items were not initially loaded in the front end. This is not the case if you use the multi-toggle option.
Do not limit the range selection for the multi-selection plug-in unless you have to.
- If the dataset is small and/or completely available in the front-end, set the limit property to 0 to enable the Select All option and allow users to select any range.
- If you have a large dataset, set a limit on the number of selected items to avoid performance issues. Also bear in mind that some actions won’t be helpful if the dataset is too big (for example, a delete operation on 2 million database entries).
When setting a limit, also display the corresponding message when the user selects more items at once than the limit allows (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification).
For single-selection 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:

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.
Open a dialog for larger tree tables with up to 8 editable columns. Save the new item at dialog level.
Navigate to a new page. This behavior should only be used for very complex scenarios that cannot be handled by a dialog (for example, tree tables with more than 8 columns). When the user presses Save in the footer toolbar of the create page, navigate back to the tree table.

Depending on the flow, an item can be in one of three different states:

New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the corresponding node. Ignore current sort, filter, and grouping criteria to keep the item visible.
Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
- Inline creation: After Save was triggered on the tree toolbar or at page level.
- Create with dialog: A tree table showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

In the context of draft handling new items are not saved at tree table level, but rather with the entire draft.

For more details, see the guidelines for managing objects (including subarticles).

Enabling/Disabling Actions

To indicate if an action can be applied to the current selection:

Enable the action if it always works, regardless of whether or not items are selected.
Enable the action if it can be applied to all selected items.
Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Let the user choose whether to apply the action anyway or cancel the action.
Only disable the action if:
- The action can’t be applied to any of the selected items.
- The number of selected items doesn’t match the action. For example, disable Compare if only one item is selected.

For more details, see UI Element – States.

If the action was applied and the items are still available, keep them selected.

Message for an action that applies to a part of a selection

Columns

Minimize the number of columns. Avoid the need to scroll horizontally in the default delivery. In the first column, show the hierarchical data, which should identify the line item. Choose the name over the ID, but if both are needed, show the name first, then the ID.

The tree table assigns the same width to each column by default. It is recommended that you overwrite this default to provide optimal space for your content (sap.ui.table.Column, property: width).

If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the browser window size results in a scrollbar. After resizing a column, a scrollbar appears if the width of the table is not enough to show all columns. If the columns use less space than is available, white space appears on the right side of the last column.

If you define the column width as a percentage, resizing one column affects the width of several or all columns. Text becomes truncated when the browser window size is reduced. This is done to make sure that all columns together fill the space of the table. A scrollbar appears only in case the automatic change of the column widths is not enough to display all columns. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

If you define the column width as “auto”, the behavior is the same as for “percentage”. In contrast to percentage, “auto” distributes the columns equally.

To decide on how to set the column width (pixel/rem/em vs. percent/auto), keep the following tips in mind:

For tables with only 2 to 3 columns, use pixel-based units. This ensures that on wide screens the values in the columns are not spread over the whole screen, which improves readability of line items.
For tables with many columns, where a horizontal scrollbar is usually needed, use pixel-based units. This avoids unintended side effects when resizing columns.
For all other tables, use whatever fits your case better.

Be cautious with mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it could also cause even more unintended side effects when resizing a column. When using percentage-based widths for one or more columns, think of the possibility to not allow end users to resize columns at all.

Alignment of Cell Content

Align column headers according to their cell content:

Texts are left-aligned.
Numbers (except for IDs), dates, and times are right-aligned.
Icons are centered.
Micro charts are left-aligned.

In addition, align amounts with currencies to the decimal point. You can do this with the sap.ui.unified.Currency control.

Note that most currencies have two digits after the decimal point, but there are exceptions, for example:

The Tunisian dinar has three digits.
The Japanese yen has no digits.

In tree tables with mixed currencies, all amounts still have to be aligned to the decimal point.

To enable positive and negative values to be identified more easily, position the minus sign to the right of the number. It is placed in the same position in every row.

For more information, see currency.

Formatting Cell Content

Note that there are different locale formats, so show dates, times, and numbers in the correct format for the user’s language/country.
If you show both a a text and an ID, consider the requirements for sorting, grouping and filtering:
- If users need to sort, group, and/or filter by both text and ID, show the text and ID in two separate columns.
- If users only need to sort, group, and/or filter by either text or ID, show the ID in parentheses after the corresponding text.
If the unit of measurement is the same for all rows, show the unit of measurement in the column header. Otherwise, show the unit of measurement within the row.
If you want to let users sort, filter, or group by amount and by unit of measure independently, put both in different columns. If you combine them in one column, offer only sorting, filtering, and grouping by amount.

Tree vs. Table

Trees are more complex than tables due to their hierarchical view. Users tend to have more problems finding items in hierarchical views than in flat lists, except where the hierarchical view is natural. By natural we mean that every child node should be part of only one parent, and this relationship between the child and parent is clear and well known.

Do

Example of an acceptable use of tree tables

Do

A clear parent-child relationship

When you use trees, you should choose broad hierarchies over deep hierarchies. Deep hierarchies make finding items more complicated. So try to reduce hierarchical levels where possible, especially if the hierarchy is not natural. Ideally, a tree should have a maximum of four levels, the first two of which should contain the most important items.

Don't

Avoid unnecessary depth in the hierarchy

Do

Favor breadth over depth in the hierarchy

You can use the following methods to reduce hierarchy levels:

Avoid single root nodes. A single root node is often used to provide a Select All feature. Since the tree control provides an extra space for a Select All feature, the root node is not usually needed.
When you use only two levels, choose a grouped table or grouped ALV over a tree table control. Expand all groups for the default delivery.
Container nodes at the top level can usually be replaced by tabs or value pickers.
Eliminate unnecessary mid-level containers, for example, by combining redundant ones.
Exercise care when using a tree due to its overall complexity. The hierarchical structure of the data does not necessarily mean that a tree control is required.

Design Concepts

The tree table can be used to display large amounts of hierarchical data. Unfortunately, tree tables have a high data density and therefore convey an immediate feeling of complexity. Ideally, tree tables with large amounts of data should only be shown if there is no other option. You should instead try the following:

Flatten the data. A list, table, or ALV is still complex, but less so than a tree table.
Break down the data into manageable chunks. Allow the user to navigate or drill down between them.
Use charts with drilldown functionality until the amount of data is more manageable.

Try to avoid horizontal scrolling in the default delivery.

Navigation

To trigger navigation on line item level, choose one of the following options:

Use a link for the attribute that identifies the row. Clicking the link triggers the navigation. This is the preferred option.
Add the RowActions column and show the navigation arrow ( ) at the end of the row. No column header text is required. The navigation column is fixed and will not scroll away. Users also cannot personalize this column. The navigation arrow triggers the navigation.
Do not use the RowActions column for actions other than navigation and deletion.

Special case: Multi-selection in a 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

When you use trees:

Choose breadth over depth.
Emphasize important values. Do not let the user run into a wall of text without guidance. You can use bold text for this.
Try to minimize the number of columns, especially if there is a large number of rows.
Optimize column width for its initial visible content. Do not automatically adjust column width based on content changes.
Do not wrap content, truncate it. End users can easily change the column width to see the full text.

Don't

Avoid truncating the initial visible content in the default delivery

Don't

Never wrap texts

Maintain a fixed layout, except when the user wants to change it.
In the default layout, use the tree column for the item name or data that identifies the row. This helps the user to choose between different items.
Create a clear and immediately understandable hierarchy. Use clear parent-child relationships. If this is not possible, add a child in different nodes to help the user find the element.

Do

Acceptable: repeat entries to optimize finding items

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

Highlight Items

To show that an item needs attention, a highlight indicator can be shown in front of the item. The highlight indicator can be used to indicate:

A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.ui.table.TreeTable, aggregation: rowSettingsTemplate)

Highlighted items

Drag and Drop

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items. These are keyboard operable and available on all browsers.

Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within a tree table, use the following options:

For dropping items as a child, use whole nodes as drop targets (sap.ui.core.dnd.DropPosition.On).
For dropping items on the same level, use the space between items as drop targets (sap.ui.core.dnd.DropPosition.Between).
If you want to allow users to drop items as a child or sibling, offer both drop targets (sap.ui.core.dnd.DropPosition.OnOrBetween).

This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop target on an item

Do not combine rearranging items within one level and sorting. If you really need to do so, make sure there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

Moving items from one node to another can be combined with sorting without any issues.

Don't

Do not combine rearranging items on the same level with sorting

Visible Alternatives to Drag and Drop

Depending on the functionality you need, use one or more of the following alternatives:

To move items up or down within a node:
Use the Move Up and Move Down buttons on the toolbar. These buttons move the selected items until the first selected item can’t be moved up / the last selected item can’t be moved down any further.
Depending on your tree, this can make sense for both leaves and nodes, only for leaves, or only for nodes. When moving a node, move the whole node and (if applicable) all its children up or down to the next position within the parent node.
Always make sure that when the user moves an item in one direction and then moves it back, the order is the same as it was before.
Do not combine the option to move items up and down with sorting.
To move items to another node:
Use Copy and Paste buttons on the toolbar.
Alternatively, offer a Move To button. Clicking Move To opens a dialog that shows all the nodes of the tree, but no leaves. Selecting an item in this dialog closes the dialog and moves the corresponding items to the selected node.
To change the level of an item:
In some trees, such as document structures, users can change the level of an item without affecting the level of parent or child items. In this case, use left and right arrow buttons ( ).

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar). Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

The context menu can be triggered for the table, row, or cell. However, we do not recommend using context menus for cells: because the content of a cell is a different touch target than the cell itself, opening a cell context menu via touch is quite hard, even in cozy mode.

Do not combine context menus with condensed mode: editable controls fill the entire space inside a cell. Because of this, context menus cannot be opened at all with touch or mouse interaction.

Tables in Object Pages

In the object page, we advise against using analytical, grid, and tree tables. Instead, use a responsive table and offer navigation to a list report with the table types mentioned above.

For more information on the use of tables within the object page, see the Tables section of the Object Page article.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting table data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button

Resources

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

Elements and Controls

Bullet Micro Chart (guidelines)
Button (guidelines)
Checkbox (guidelines)
Combo Box (guidelines)
Comparison Micro Chart (guidelines)
Date Picker (guidelines)
Filter Bar (guidelines)
Formatting (guidelines)
Icon (guidelines)
Icon Tab Bar (guidelines)
Input (guidelines)
Label (guidelines)
Link (guidelines)
Multi-Combo Box (guidelines)
Multi-Input Field (guidelines)
Select (guidelines)
Stacked Bar Micro Chart (guidelines)
Table (guidelines)
Text (guidelines)

Implementation

Tree Table (SAPUI5 API reference)

Responsive Table

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.

Responsive table

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.

Don't

Don't use a responsive table as a form

See the table overview to decide which SAP Fiori table is most suitable for your needs.

Responsiveness

The responsive table is optimized for viewing one line item at a time with no scrolling or only vertical scrolling, irrespective of the display width.

On smartphones, only the most important data remains in the one-column or two-column table, while all other data is moved to the space between two item rows, known as the “pop-in area”.

In this area, data for the corresponding cell is provided as a label/value pair. The label is defined by the column header, and the value is taken from the corresponding cell. Labels can be displayed next to the value or above the value.

Within the pop-in area, the label/value pairs can be displayed in the following ways (sap.m.Table, property: PopinLayout):

Block: Label/value pairs are listed one below the other.
GridSmall: Label/value pairs are displayed next to each other in equally spaced grid cells. An additional column is shown for each 13 rem of available width (208 px with default browser settings). If the number of grid cells exceeds the available width, the grid cells wrap. On S size, this layout transforms automatically to a block layout.
GridLarge: The display logic is the same as for GridSmall,, but grid columns come with a larger minimum width (26 rem instead of 13 rem).

In all layouts, you can show the labels next to or above (recommended) the corresponding data.

The responsive table uses all the available space, and does not provide any padding. If there is space around the table, it comes from the spacing defined for the surrounding layout container.

Information

The GridSmall and GridLarge layouts are not available in all browsers. If the chosen layout is not available, it is automatically changed to Block layout.

Responsive table displayed on a smartphone (size S)

Responsive table displayed on a tablet (size M)

Responsive table displayed in compact mode on a desktop computer (size L)

The responsive behavior is optional. If it is not used, the responsive table 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.

A typical responsive table

Hide the information column for a width smaller than 570 px.

Hiding the information column

Move the column “vendor” to the pop-in area for a width smaller than 460 px (sap.m.Column, properties: demandPopin, minScreenWidth).

Moving the vendor column to the pop-in area

Move the column “limit” to the pop-in area for a width smaller than 350 px (sap.m.Column, properties: demandPopin, minScreenWidth).

Moving the limit column to the pop-in area

Move the column “price” to the pop-in area for a width smaller than 270 px (sap.m.Column, properties: demandPopin, minScreenWidth).

Moving the price column to the pop-in area

If you still need to support smaller screens, values can be moved below the corresponding labels inside the pop-in area. In these examples, this happens for a width smaller than 220 px (sap.m.Column, property: popinDisplay).

Pop-in area: Moving the data below the labels

Example for GridLarge Layout

A more complex responsive table.

A more complex responsive table (full screen without pop-in content)

In this example, the Average Occupancy Rate and Available In columns move to the pop-in area if the screen width is less than 1900 pixels.

GridLarge layout - 'Average Occupancy Rate' and 'Available In' columns move to the pop-in area

If the width is less than 1500 pixels, the Average Stay column moves to the pop-in area.

GridLarge layout - 'Average Stay' column moves to the pop-in area

If the width is less than 1100 pixels, the Description column moves to the pop-in area. Since all four columns in the pop-in area do not fit into one row, the pop-in content wraps.

GridLarge layout - 'Description' column moves to the pop-in area

If the width is reduced even further, the Details column moves to the pop-in area. On this narrow screen, only one column fits into one pop-in row, so it looks exactly like the block layout.

GridLarge layout - 'Details' column moves to the pop-in area

Layout

The optional title bar consists of the title of the responsive table, an item counter, variant management, and the toolbar.

The filter infobar appears when the responsive table is filtered, and shows information on the filter settings.

The column header shows the label for each column. In addition, it allows the user to resize the column.

The collection of items, or rows, occupies the main part of the responsive table.

You can add aggregation information (such as totals) on the table footer.

A More button can be shown if you do not want all items to be loaded at the start (known as “lazy loading”). Ideally, you should use scrolling to load more items instead of choosing the More button.

Schematic visualization of the responsive table

Components

The title bar contains the title of the responsive table, an item counter, variant management, and the toolbar.

The toolbar can contain entry points for the view settings dialog and the table personalization dialog, as well as view switches in the form of a segmented button, and buttons for Add, Edit, and other actions.

Beneath the toolbar, display a filter infobar (which itself is a special toolbar) if the responsive table is filtered.

To format within items, apply the guidelines for formatting data. Controls commonly used inside items are the object identifier and the object number. For more information about these controls, see object display components.

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

The More button loads more items to the front end if not all items have yet been loaded.

Components of the responsive table

Behavior and Interaction

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

Table Level

Scroll

The height of the table is defined by the number of items it contains. It does not have a scroll container on its own, but is scrolled together with the app (in contrast to the grid table and the analytical table).

If the table works in “growing” mode, it only loads a few items at first. Additional items are only loaded (and rendered) on request. The “request” can either be triggered by scrolling (preferred), or by clicking the More button.

Same table, different number of items

When the user scrolls, the title bar, column headers, and filter infobar can stick to the top of the surrounding layout container (sap.m.Table, property: sticky).

Information

The “sticky” feature comes with some limitations:

It is not available on all browsers. In non-supporting browsers, the corresponding areas (title bar, column headers, filter infobar) are not fixed on top of the surrounding layout container while scrolling.
Certain layout containers suppress the sticky behavior, such as the grid layout. The same happens if the table is placed within the object page.
If focus is set to a fixed column header, the table is automatically scrolled to top.

Sticky table title and sticky column header

Merge Duplicates

To simulate the behavior of row spanning, you can merge cells of consecutive rows inside one or more columns automatically if they contain the same value (sap.m.Column, properties: mergeDuplicates, mergeFunctionName).

Use the merge feature if you expect the column to contain duplicate entries, and it makes sense to group them. In the example screenshot, the Supplier, Product, and Dimensions columns reflect a hierarchical structure: Suppliers have products, which in turn have dimensions. Because suppliers typically have multiple products, merging duplicate entries for the supplier column makes the table easier to read. Note, however, that when the user sorts the table by another field, the hierarchy changes and the merged items are regrouped accordingly.

Do not use the merge feature:

If duplicate entries are not part of the design. If consecutive table rows happen to have the same values at runtime, this alone isn’t a valid reason to group them.
If the corresponding column can contain blank cells. Otherwise, it is cumbersome to differentiate between blank values and merged values.

Supplier column merges duplicates in consecutive rows

Merged columns with multiselection

Select

A responsive table can have one of the following selection modes (sap.m.Table/ sap.m.ListBase, property: mode):

None: Items cannot be selected (sap.m.ListMode.None).
Note: Line items can still use the sap.m.ListType “navigation”, which allows click handling for specific line items. Only use this option if the click triggers navigation to a corresponding details page.
Single select master: One item in the responsive table can be selected. Items are selected by clicking the whole row. The single select master mode has no obvious visual cues, such as checkboxes or radio buttons. It only provides a light blue background for the selected state. Because of this, it can barely be differentiated from tables without selection (mode: None). Single select master is the preferred mode for single selection (sap.m.ListMode.SingleSelectMaster).
Single select left: One item in the responsive table can be selected. For this, the responsive table provides radio buttons on the left side of each line item. This mode is not recommended (sap.m.ListMode.SingleSelectLeft).
Multi select: Users can select one or more items using the checkboxes on the left of each line item. The Shift key can be used to select a range. Users can (de)select all items using the Select All checkbox to the left of the column header (or CTRL+A). Select All should (de)select all items that the user can reach by scrolling. (sap.m.ListMode.MultiSelect).
Another multi select variant is to not provide a Select All option, but just a Clear All check box in the same place (property: multiSelectMode, value: ClearAll).

Keyboard: If the focus is on a row, the space bar selects the corresponding item.

Responsive table without selectable items

Single select master

SIngle select left, with radio buttons. Use only if row clicks are used for something else.

Multi select with 'Select All' checkbox

Multi select with 'Clear All' button

Group

When items are grouped, a group header is displayed. The group header is not interactive.

Group headers

Show Aggregations

Show aggregations (such as totals) on the table footer (sap.m.Column, aggregation: footer).

Don’t show aggregations in “growing” mode. In “growing” mode it isn’t clear which values are being aggregated; only the items currently loaded in the front end, or all items.

Table footer displays aggregated total

Load Items

When the responsive table fits the general requirements for your use case, always consider ways to reduce the amount of data loaded in the responsive table with, for example, filters, graphics, aggregation of information, and navigation. Keep in mind you should use it only to display moderate amounts of data, including factors like number of items and content complexity.

To show more than 100 items, use the “growing” mode (sap.m.Table/ sap.m.ListBase, properties: growing, growingThreshold, growingScrollToLoad, growingTriggerText). The “growing” mode allows the user to load only the first few items. Additional items are only loaded (and rendered) on request, which improves performance. You decide whether the user triggers the request by scrolling (preferred) or by clicking the More button.

If you use the More button, show the number of items already loaded and the total number items below the More text, if possible.

Do not show aggregations in “growing” mode. Also, do not display an item count on the table toolbar if “growing” mode is used. Use the count on the More button instead.

Guidelines

If you expect users to work with large amounts of data, use the grid table because it is optimized for handling large data sets.

The growing mode will only help to reduce the amount of data loaded at once but the limits to the overall amount of data still apply.

Load on scroll

Column Header Level

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

Resizing Columns

If you implement column resizing, users can resize the columns as follows:

Mouse interaction: The user drags the separator line between two columns. Double-clicking the line optimizes the column width based on the length of the currently visible data and the label of the column header.
Touch interaction: As for mouse interaction, but with a larger target touch area.
Keyboard interaction: When the focus is on the column header, Shift+Right increases the width of the focused column. Shift+Left decreases the width.

When a column is resized, the other columns can keep their original width or adapt their width. This depends on the column width settings:

If column widths are set in pixel-based units (px, em, rem), the resized column is adapted and the columns that follow are moved accordingly. The width of all the other columns is not affected. If the visible columns don’t use the full width of the table control, empty space is added. If the visible columns exceed the width of the table control, one or more columns move to the pop-in area.
If all column widths are set as a percentage or as “auto”, resizing one column might also result in automatic resizing of some or all other columns. The position of the resized column might also be affected. This ensures that the full table width is used and no white space is added.

Developer Hint

To enable resizable columns, implement the plugin:
sap.m.plugins.ColumnResizer.

Resizing a column

Line Item Level

Delete Single Item Rows

To delete single item rows, use the table in the mode “delete” (sap.m.Table/ sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This adds Delete buttons to each line item. Clicking this button triggers the deletion of the corresponding line item. (Keyboard: If the focus is on the row itself, the Delete key can be used to trigger the Delete button.)

Do not use this mode if deleting multiple lines at once is the preferred use case.

Delete is a mode of the responsive table and therefore cannot be used together with single selection or multiselection.

Responsive table in 'Delete' mode

Highlight an Item

To highlight an item, use the “highlight” indicator (sap.m.ColumnListItem, properties: highlight).

Highlighted item

Navigate

To allow navigation from a line item, use an item with the type “navigation” (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This creates an indicator at the end of the line (“>”) and the entire line item becomes clickable (keyboard: if the focus is on the row itself, the Enter key triggers navigation). If the user clicks on the line, navigate to a new page containing line item details. In rare cases, you can also use the navigation mode for category navigation, without navigating to another page.

By contrast, clicking an interactive control within a line item does not trigger the navigation event. Instead, the corresponding control handles the click event.

If no navigation is possible, set sap.m.ListType to “inactive”.

“Navigation” is a list item type and therefore cannot be used together with “edit”, or in combination with click events for the entire item (“active”).

Navigation indicator

Indicate Navigated Item

When multi-selection 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 only (multi-selection table with navigable items), you can display a “navigated” indicator to mark the item that is currently open (sap.m.ColumnListItem, property: navigated).

Navigated item

Edit Line Items

To allow editing for a line item, set sap.m.ListType to “detail” within the corresponding item (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive). This will create an Edit button at the end of the line. Clicking the button triggers the edit event (keyboard: If the focus is on the row itself, the F2 key triggers the Edit button). Use this event to switch the corresponding line item to edit mode.

Edit is a list item type and therefore cannot be used together with “navigation” or in combination with click events for the entire item (“active”).

Edit button

Click an Item

Items as a whole can be clickable. An event is fired by clicking on the item (anywhere where there is no interactive control inside the item). Apps can react on the event, for example, by opening a dialog (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Active or sap.m.ListType.DetailAndActive).

Active elements do not have a visual indication and can therefore not be differentiated from non-active elements.

Active is a list item type and can therefore not be used together with “navigation” or “edit”. In addition, “active” uses the whole item as a clickable area and therefore cannot be used together with a single-selection table.

Active element

Drag and Drop

One or several items can be repositioned within a table or moved to other UI elements using drag and drop operations (sap.m.ListBase, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop

Whole item as drop target

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column). Context menus can be implemented for a specific table or row.

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or Shift+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Responsive table with a context menu

Cell Level

Showing Information

In contrast to traditional tables (such as the analytical table or the tree table), a cell can contain more than just one line of text.

Several lines of text within one cell

Add Controls

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

Controls inside cells

Any control can be placed inside cells

A cell can contain more than one control and more than one data point.

With the View Settings dialog, users can sort, filter, and group by each of these data points.

Several controls per cell

You can also have different controls in different rows in the same column. This could be the case if one item is locked, but another item is in edit mode, for example.

Different controls per column

Guidelines

Responsiveness

In most cases, the auto pop-in mode is sufficient. If you need to optimize further, first try to adapt the columns to influence the automatic behavior (sap.m.Column, properties: autoPopinWidth, importance). For example, set the priority for the two or three most important columns to “High” (identifying column, key attribute).

While the pop-in layouts GridLarge and GridSmall make better use of the available width, they also only look good with content that is specifically designed for these pop-in layouts. If you have text-only tables with only one value per column, use the Block layout (sap.m.Table, property: popinLayout).

Place the column header labels in the pop-in area above the corresponding values (sap.m.Column, property: popinDisplay, value: Block). This avoids alignment issues with different content. Be aware that the labels get top-aligned with the adjacent content.
Only place the label next to the corresponding value under the following conditions (sap.m.Column, property: popinDisplay, value: Inline):

The values are text-only (no input fields, icons, images, micro charts, and so on)
The available space is at least the double the width of size S.

This avoids truncation or “over-wrapping” of the labels and content.

If a column does not have a column header text (for example, if it always contains the same button with its own label), do not show the header text as a label in the pop-in area either (sap.m.Column, property: popinDisplay, value: withoutHeader). If you forget this setting, you will see an empty space followed by a colon (“:”).

Information

The GridSmall and GridLarge layouts are not available in all browsers. If the chosen layout is not available, it is automatically changed to Block layout.

Table Title

Implement the table title by using a title control in a toolbar.

Use a table title only if the title of the table is not indicated in the surrounding area. Do not use a table title if it simply repeats text that is already above the table. For example:

A pricing conditions table is the only control on a tab labeled Pricing Conditions.
A section or subsection on an object page contains only one table.

Use a table title if you need the item count, table toolbar, or variant management. To avoid repeating text, feel free to use generic text as a table title, such as Items.
Exception: If the surrounding area contains the table title, and both the item count and toolbar can be added to the surrounding area, no additional table title is needed.
Example: An object page (sub-)section contains only one table. In this case, add the item count and the table toolbar to the (sub-)section header.

Developer Hint

Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table.

If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

If you use a table title, show either a title for the table, with or without variant management, or an item count in the following format:

Items (2,534)

The item count in the table title includes all the visible items that a user can reach by scrolling. Group headers are not included.

Remove the item count in the table title if there are zero items. Do not use an item count together with “growing” mode.

If possible, keep the title bar sticky (sap.m.Table, property: sticky).

Table title with item count

Selection

For single selection cases, use the selection mode “single select master”. This is the recommended single-selection mode for list-detail scenarios within the flexible column layout. If you use it there, do not show a “navigated” indicator.

In rare cases, you can also use the click area for the row for another purpose (for example, to open dialogs). As a result, the click area cannot be used for selecting the row. In these cases only, use the “single select left” selection mode to offer a radio button as an additional click area for each row. To avoid confusion, make sure that the first data column does not contain radio buttons in the default delivery.

For all single selection modes, make sure that one item is initially selected. Otherwise, the user cannot return to the initial state. A selected item can only be deselected by selecting another item.

In multiple selection mode:

Prefer Select All over Clear All
Use Clear All only for tables with a large number of items (more than recommended above), where loading all items to select them would harm performance.
To avoid confusion, don’t show checkboxes in the first data column in the default delivery.
Make sure that the Select All checkbox (de)selects all items the user can reach by scrolling. This is only possible if all items are rendered.
Never disable the selection checkbox. If an action can’t be performed on a specific item, inform the user after the corresponding action has been triggered. For more information, see Enabling/Disabling Actions.

Don't

Single selection left - Don't show radio buttons in the first column in the default delivery

Don't

Multiple selection - Don't show checkboxes in the first column in the default delivery

Do

Use the selection mode "single select left" if clicking the row is used for something else (such as navigation)

Do

Use the selection mode "single select master" in all other single selection cases

Developer Hint

Select All is only applied to items that have already been loaded to the front-end server. All other items are not (de)selected before they are loaded, such as items added via lazy loading with growingScrollToLoad. This conflicts with the guideline that all items the user can reach by scrolling must be (de)selected.

To process all items, listen to the selectionChange event and to its selectAll flag. This indicates whether the Select All checkbox was triggered. As soon as an action is triggered, process the items accordingly. Depending on the number of items, consider processing them in the back end.

Loading Data

To indicate that the table is currently loading items, use the busy state. (sap.m.Table, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Table in busy state while loading data

Errors and Warnings

To indicate that the table contains items with errors or warnings, show a message strip above the table. On the message strip, provide information on errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

To indicate an error in a single row, see Item States below.

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

Developer Hint

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

Table containing errors

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.

Don't

Do not distribute just a few columns across the full width

Do

Use a fixed column width instead

Column Headers – Best Practices

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

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

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.

Do

Wrap column headers if columns are not resizable

Do

Truncate column headers if columns are resizable

Column headers (sap.m.Column, aggregation: header) usually contain links or text-based controls.

Column headers can also contain other kinds of SAP Fiori controls. However, the column header cannot be aligned vertically, making it difficult to use many controls in the column header. Using other kinds of controls also creates problems with pop-in behavior and could thus lead to accessibility issues. Therefore, exercise caution when using them in a column header.

Accepted: Link as column header text (rarely used)

Accepted if responsiveness is taken into account: Text plus search field

If a column cell contains several fields, use an umbrella term in the column header (such as Address for fields like Street, ZIP Code, and City).

For text and ID fields, use a generic label (for example, Employee for Name and ID).

If none of these are possible, separate the labels with “/” (for example, Name / Status).

For boolean values, such as checkboxes, find a descriptive text for the column header.

Horizontal Content Alignment

For alignment of cell content, follow the guidelines below (sap.m.Column, properties: halgin, valign, sap.m.ColumnListItem, property: VAlign). Align the column header horizontally according to the content of the cell.

Exception: Secondary information in a column always follows the alignment of the main information.

Left-Align

Left-align: Text, IDs, phone numbers, URLs, passwords, and email addresses.

Left-align text

Left-align: Status information

Left-align status information

Right-Align

Right-align: Dates and times (to ensure comparability for most formats and locales)

Right-align dates

Right-align: Numbers and amounts, except IDs, to ensure figures are comparable

Right-align numbers

Center-Align

Center-align: Icons, images, and avatars

Keep the column name for center-aligned columns as short as possible to avoid excessive white space between columns. Alternatively, you can leave the column header empty on the visual UI, and use the invisible text control to provide information on the column content for screen reader listeners.

Align buttons with the content hierarchically

Always place buttons directly next to their content. Do not add an additional column for buttons. If you have more than one button, display them next to each other. Order the buttons based on importance. The most important button is on the left, the least important on the right. If there is not enough space to display them all in one line, move the buttons from the right onto the next line one by one. Do not use more than two buttons per line item.

Vertical Content Alignment

Top-align where possible to facilitate reading the content on one line.

Do not use top-alignment if it results in a peculiar layout. This usually happens when controls that need more vertical space are combined with text-only controls, such as input fields. In this case, try center-alignment instead and fine tune it until the layout fits.

Do

Use top-alignment where possible

Don't

Don't use top alignment if it doesn't make sense

Content Formatting

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

As a key identifier of an item, use an object identifier. Show the key identifier in the first column. For more information, see object display components.

If the table width is small, do not hide this column or move it to the pop-in area.

Object identifier

Strings with IDs: If the responsive table contains more single-line data, show the ID in brackets after the corresponding string.

This minimizes the line height.

For items with a small line height, place the ID in brackets after the corresponding string

If displayed as a link, use the whole text as the link

Strings with IDs: If line height is already large, show the ID below the corresponding string. Use the object identifier to do so.

For items with a large line height, place the ID below the corresponding string

Is displayed as a link, use only the first line as the link

If there is more than one key identifier (for example, First Name and Last Name), display these columns first and show the values in bold text.

Several key identifiers

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

For status information on text: If the status is actionable, add a transparent icon button next to the text.

Semantic colors on text

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

For example, use text.

Do

Wrap text

Don't

Don't truncate text

For editable content, use input fields and other interactive controls within the table cells. If you need to offer edit mode, change your text controls (labels, text, and links, to input fields or other appropriate controls) as soon as you switch to edit mode, but not before.

You can do this by changing the control or, in more complex cases, by exchanging the whole responsive table.

Interactive controls – Inline

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

Leave empty fields blank

Numbering Items

If the item number has four digits/letters or less and is equally important as the corresponding description, concatenate the item number with the description and show it in one column.
If the item number has five digits/letters or more, or if it is more important than the corresponding description, for example, when no description is available, use a separate column for the item number.
If the item number is more like an ID in regards to its description, use ID formatting, like Description (ID).

For short numbers, add the item number to the description

Flag and Favorite

Place the flag or favorite marker in the first column (in the default delivery). To change the settings, users need to drill down into the object itself.

Item marked as a favorite

Empty Tables

Try not to display an empty responsive table. If there is no way around this, provide instructions on how to fill the table with data (sap.m.Table/ sap.m.ListBase, properties: showNoData, noDataText).

Examples:

If a table is initially empty, provide at least a basic text:
No items available.
Overwrite this whenever a hint can be provided on how to fill the table with data.
If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
To start, set the relevant filters.
If a table is used together with a filter bar and the filter does not return results, use the following text:
No data found. Try adjusting the filter settings.

Adapt the texts above if:

The standard text is not precise enough for your use case (for example, a search is also offered, or only the search is offered).
The standard text is misleading (for example, if the data is filled based on a list-detail pattern instead of filter settings).

Remove the item count in the table title if there are zero items.

Provide meaningful instructions

Displaying Boolean Values

If a column contains Boolean values, such as “Yes” or “No”, show a read-only checkbox next to the texts.

The supplementary checkbox makes it easier for users to see at a glance which items are “true” (checked) and which are “false” (unchecked).

Developer Hint

Use sap.m.checkbox with the Horizon theme and set the editable property to “false” to get the read-only variant. Add the checkbox next to the existing text value. The text itself should remain unchanged.

Avoid showing only text for Boolean values

Boolean values with read-only checkboxes for easier scanning

Item States

To show that an item is unread, use the corresponding flag (sap.m.Table, property: showUnread, sap.m.ColumnListItem/ sap.m.ListItemBase, property: unread). This shows most of the content in bold font.

An unread item

To show that an item has been modified, for example, within the global edit flow, add the string (Modified) at the bottom of the column that identifies the line item.

A modified item

To show that a modified item contains an error (for example, within the global edit flow), add the string (Contains errors) at the bottom of the column that identifies the line item. To do this, use an object status control with the error state (sap.m.ObjectStatus, property: state, value: sap.ui.core.ValueState.Error).

In addition, highlight the row accordingly (sap.m.ListItemBase, property: highlight). A row with errors should be highlighted in all use cases – for example when the field is visible in the row in edit mode.

A modified item with an error

To show that an item is locked, use a transparent button with the corresponding icon and the text Locked by [Name] at the bottom of the identifying column. The user can click the button to open a quick view of the person.

A locked item

To show that an item is in a draft state, use a transparent-style button with the text Draft at the bottom of the identifying column. The user can click the button to open a popover showing the timestamp of the last change.

Item in draft state

Show only one state at any one time.

Highlight Items

To show that an item needs attention, you can show a highlight indicator next to the item. The highlight indicator can indicate:

A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It doesn’t tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.m.ListItemBase, property: highlight)

Highlighted items using status colors

Highlighted items using industry-specific (indication) colors

Numbers and Units

If the following conditions all apply, show the unit of measurement in the column header:

The unit of measurement is the same for all rows
A single cell contains only one amount with the unit of measurement
The column header does not scroll away

In all other cases, show the unit of measurement together with the corresponding amount within the row.

Show the unit of measurement in the same column as the corresponding amount.

For numbers with units, show the correct formatting by using the object number control.

Object number

For the most important number with its unit, show the correct formatting by using the object number control and the emphasized flag.
Exception: If all numbers are of equal importance, emphasize none of them.

If the table width is narrow, do not hide this column or move it to the pop-in area.
Exception: If the column containing the object identifier and the column containing the key attribute do not fit together on the screen, move the column containing the key attribute to the pop-in area.

Object number (emphasized)

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.

Use drag and drop only in addition to existing visible UI elements

If you offer drag and drop for rearranging items within the table, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop targets in between items

Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

When combining rearranging items with grouping, be aware that moving items to another group also means that a value of the dropped item changes: because grouping is based on values in a column, the dropped item needs to take on the value of the target group for the corresponding column. If this is not wanted, do not allow users to rearrange items in grouped tables.

Example:
A table is grouped by availability. An item is moved from the group “Not Available” to the group “In Stock”. In this case, the moved item needs to change its availability to “In Stock” to match the target group. If changing the value doesn’t make sense, only allow users to rearrange the items within the same group, or don’t allow rearranging at all.

Don't

Don't combine rearranging items with grouping, unless you know exactly what you're doing.

Context Menu

Use the context menu only to give users a quick way of accessing functions that are already available elsewhere (for example, as buttons in the toolbar).

Don’t just offer actions in the context menu itself, as users might not realize that these actions are available at all.

The context menu can be triggered for the whole table or per row.

Actions

To trigger actions on multiple items, use a multiselection table (sap.m.Table, property: mode, value: sap.m.ListMode.MultiSelect), and offer the corresponding actions on the table toolbar. Keep the table toolbar sticky (sap.m.Table, property: sticky).

Do not offer actions for multiple items if the table is expected to have fewer than 10 items in most cases.

To trigger actions on a single item only (sap.m.Table, property: mode, value: sap.m.ListMode.SingleSelectMaster):

Show the actions on the table toolbar.
In rare cases, show the actions within the line item. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. In this case, show the action trigger near the content to which it belongs. Do not add a specific column for actions. Use a button, unless the action trigger belongs to a link. Hide the action in rows for which it is not applicable.
Don’t bundle inline actions that don’t belong together under an unspecific label, such as Misc, Actions, … , or similar.

Do

Inline actions

Don't

Don't combine unrelated inline actions

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

Delete: Use “Delete” table mode (sap.m.Table/ sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This places a Delete button at the end of each row.

Delete button

Navigation: Use the “Navigation” column list item type (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This places a Navigation indicator at the end of each row.

Use this to navigate to a new page containing line item details. In rare cases, you can also use this for navigation within the table without navigating to another page.

Navigation indicator

Edit: Use the “Detail” column list item type (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail). This places an Edit icon at the end of each row.

Edit button

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.

For information on enabling and disabling actions, see Enabling/Disabling Actions.

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:

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.
Open a dialog for larger tables with up to 8 editable columns. Save the new item at the dialog level.
Navigate to a new page. This behavior should only be used for very complex scenarios that cannot be handled by a dialog (for example, tables with more than 8 columns). When the user presses Save in the footer toolbar of the create page, navigate back to the table.

Depending on the flow, an item can be in one of three different states:

New: The item was just created inline and is in edit mode (for example, after pressing the Create button). It is highlighted with a visual indicator (information state).
Recent: The item was just created and is in read-only mode (for example, if Create leads to a dialog, and Save was triggered within the dialog). In this case, keep the item highlighted and display it as the first item of the table. Ignore current sort, filter and grouping criteria to keep the item visible.
Added: The item has been fully added. It follows the sort, filter, and grouping settings and also loses the visual highlight. This state is used after:
- Inline creation: After Save was triggered on the table toolbar or at page level
- Create with dialog: A table showing one or several items with the state “Recent” gets updated (for example, after sorting, filtering, or grouping, or when the browser is refreshed).

In the context of the draft handling new items are not saved on table level, but rather with the entire draft.

For more details, see the guidelines for managing objects (including subarticles).

Add button in table toolbar

New item as first row in edit mode

Saved new item, still highlighted, still the first item

Editable Content

For editable content, use input fields and any other interactive controls within the table cells that meet your input needs.

All SAPUI5 controls can be used.

If you need edit mode, change your text controls, such as label, text, and link, to input fields, or other appropriate controls as soon as you switch to edit mode, but not before.

You can do this by exchanging the control or, in more complex cases, by exchanging the entire responsive table.

For mass editing items:

Provide multiselection (sap.m.Table/ sap.m.ListBase, property: mode, value: sap.m.ListMode.MultiSelect).
Provide an Edit button.
If several items are selected, choosing the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

For details, see mass editing.

View Settings: Sort, Filter, Group

Sort, filter, and/or group settings are handled in the view settings dialog. This dialog can provide any combination of these three settings, including just one setting, such as sort only.

If sorting, filtering, and/or grouping are a common use case in your app, offer one, two, or all three of the corresponding features in one or more view settings dialogs. Note: Do not offer these features if the table is expected to have only a small number of entries (up to 20 in most cases).
If filtering is a main use case, do not offer filtering in the view settings dialog. Use the filter bar instead.

To trigger the view settings dialog, provide several buttons, one for each of these view settings. Each button opens a view settings dialog that contains only the relevant page.

You should always use only the view settings you really need. For example, do not offer grouping if it does not support your use case well.

Using the view settings dialog allows you to define several sort, filter, and/or group settings per column. Therefore, you can sort, filter, and/or group a column with several data points independently by each data point.

Several triggers for the different view settings (sort, filter, group)

Sort

Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the first column in the default delivery. Use the primary data point from this column.

If you offer sorting, offer it for each data point. In other words, allow sorting by both the primary and secondary information in a column. Allow sorting in both directions, ascending and descending. The descending sort order must always be the exact reverse of the ascending sort order.

For each data point, provide a meaningful sort order. For example:

Sort text alphabetically
Sort numbers by their value
Sort status information by the severity of the status:
- Ascending: Sort status information from positive to negative, with neutral last.
- Descending: Sort status information from negative to positive, with neutral first.

Object status sorted ascending, with neutral status last

Object status sorted descending, with neutral status first

- Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
- Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Object status sorted ascending and alphabetically, from positive to negative with neutral last

Object status sorted descending and alphabetically, from negative to positive with neutral first

Filter

To display the current filter state, use the infobar below the table title. Clicking the infobar opens the view settings dialog on the filter page.

Show the infobar only if the filter settings are not shown somewhere else. For example, do not show the infobar for settings taken in the filter bar or in a select placed in the table toolbar.

If the infobar is shown, provide an option to reset all corresponding filters on the infobar.

Keep the infobar sticky (sap.m.Table, property: sticky).

Developer Hint

To display the current filter settings on the infobar, consider using the list formatter (sap.ui.core.format.ListFormat).

Filtered table

Group

To display the current group state, group headers are shown.

On the group header, show the following text (sap.m.GroupHeaderListItem, property: title):

[Label of the grouped column]: [Grouping Value]

Do not use several values on the group header.

Grouped table

If there is no grouping value, show the following text:
[Label of the grouped column]: (Not Available)

This is the case if you have a group of items that don’t have a value for the grouped column.

Grouped table, with missing grouping value

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.

View settings and table personalization icons

Persist the column layout settings. When a user reopens the app, show the responsive table with the same column layout as last defined by this user.

Tables in Object Pages

For more information on the use of tables within the object page, see the Tables section of the Object Page article.

Export to Spreadsheet

On the table toolbar, apps can provide a menu button for exporting table data to a spreadsheet. For the export, use the export to spreadsheet function.

'Export to Spreadsheet' menu button

Paste

To paste data from the clipboard to the table, the browser functionality for paste can be used (Ctrl+V or browser context menu).

If the focus is on row level, the app has to take the data from the clipboard and add it to the corresponding controls within the table.
If the focus is on an editable control within the table, the control gets the data automatically.

Pasting via context menu does not work if a custom context menu is used.

Properties

sap.m.Table

The following additional properties are available for the responsive table:

The property: fixedLayout defines the algorithm the control uses to define column width. Setting it to “false” would perform automatic calculations for the column width, based on the longest non-breakable content. You should always set it to “true” for performance reasons. Exceptions are permissible if the table has only a few columns for a large width and fewer than 10 rows are displayed.
The property: backgroundDesign defines the background on which items are rendered. Use the default value.
The property: showOverlay provides an overlay on the whole table, which prevents use of the responsive table. This is used within the list report floorplan to mark the table as outdated after filter settings have been changed but the new filter settings have not yet been applied. Do not use it in other cases.
The property: inset adds a margin on all sides of the responsive table.
The property: headerText is a simple way to set the table title if you just need a title. However, do not use any of the following:
- A separate toolbar
- variantManagement
- headerToolbar aggregation
The property: headerDesign affects the appearance of the header if the theme supports it. Leave the default value as it is.
The property: footerText adds a small additional row below the table footer or last item. This row can contain text only. Do not use this property.
The property: width defines the width of the whole table.
The property: includeItemInSelection uses a click on the whole line item to select the corresponding item if the responsive table is in a selection mode. This competes with other settings like “Navigation” or “Active” and should therefore not be used.
The property: enableBusyIndicator automatically shows a busy indicator while data is loaded. (In contrast to the property: busy, where the application can control when the table is set to busy state)
The property: modeAnimationOn does not have any effect. Do not use it.
The property: showSeparators allows you to show all, none, or some separators. The default setting, which is to show all separators, is to be used.
The property: swipeDirection allows you to define the direction in which to swipe if additional actions are hidden behind a table row. This works only on touch devices. Do not use this property.
The property: rememberSelections leaves items selected even if they are not currently visible, for example, through filtering. If this behavior is not wanted, set the flag to “false”, but you should do so only in exceptional cases.
The property: busy sets the table to a busy state. While in busy state, the whole table cannot be used and items cannot be read due to an overlay.
The property: busyIndicatorDelay defines the time after which a busy state is shown after the responsive table has been set to this state. Use the default value.
The property: visible shows the table (“true”) or hides it (“false”).
The property: tooltip does not have an effect. Do not use it.
The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). Do not use it.

sap.m.Column

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

The property: width defines the width of the column in all units allowed by HTML, such as em, rem, %, and px.
The property: styleClass is used if you need to change the visual design of a column. Do not use this, but use the default style instead.
The property: visible shows or hides the column.
The property: tooltip does not have an effect. Do not use it.

sap.m.ColumnListItem

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

The property: selected allows an item to be selected programmatically.
The property: counter does not have any effect. Do not use it.
Do not use the property: busy.
Do not use the property: busyIndicatorDelay.
The property: visible shows or hides the item.
The property: tooltip adds a tooltip to a whole row. The tooltip is only shown on mouse interaction. It will not work on tablets or smartphones. Do not use it.

Resources

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

Elements and Controls

Analytical Table (guidelines)
Feed List Item (guidelines)
Footer Toolbar (guidelines)
Grid Table (guidelines)
Object Identifier (guidelines)
Object Number (guidelines)
Table Personalization Dialog (guidelines)
Table Toolbar (guidelines)
Tree Table (guidelines)
Variant Management (guidelines)
View Settings Dialog (guidelines)

Implementation

Responsive Table (SAPUI5 samples)
Column (SAPUI5 samples)
Column List Item (SAPUI5 samples)
Responsive Table (SAPUI5 API reference)
Column (SAPUI5 API reference)
Column List Item (SAPUI5 API reference)

Grid Table

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.

Grid table shown on a desktop

Grid table shown on a tablet

Layout

Select All – The Select All checkbox selects or deselects all items.
Column header – The column header allows the user to resize and rearrange columns. It also provides access to a menu with column-specific commands.
Selector cells – The selector cells allow the user to select one or more items.
Items – The collection of items, or rows, occupies the main part of the grid table.

Schematic visualization of the grid table

Components

A grid table does not consist of other elements. However, it is common to use a toolbar above the grid table.

The toolbar can contain entry points for the view settings dialog and the table personalization dialog or for the p13n dialog, as well as view switches in the form of a segmented button, and buttons for Add, Edit, and other actions.

Behavior and Interaction

A grid table is quite restricted in terms of its content.

Table Level

Scroll

A grid table allows horizontal and vertical scrolling (sap.ui.table.Table, property: navigationMode, value: Scrollbar).

You can add any number of line items to the grid table, which uses “lazy loading”.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.Table, property: rowHeight).

The grid table is optimized to allow faster scrolling within the first 1000 items.

Scrollbar

Select

Selection Mode

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

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

A non-selection grid table

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

A single-selection grid table

Multiple selection: One or more items can be selected. The grid table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back. The Shift key can be used to select a range.

For multiple selection, you can choose between two variants.

Multi-toggle mode (property: selectionMode = MultiToggle)
Multi-selection plug-in (sap.ui.table.plugins.MultiSelectionPlugin)

These variants behave differently when the user selects more items than are currently loaded in the front end.

Multi-toggle

In multi-toggle mode, you can offer a Select All checkbox to the left of the column header (property: enableSelectAll). Selecting this checkbox selects or deselects all items that are currently loaded in the front end (keyboard: CTRL+A). All other items are not selected/deselected. If the application data is stored in the back end, scrolling down further can reveal additional unselected items. The same can happen with range selections if not all items in the selected range have been loaded to the front end.

Multi-selection plug-in

If you use this plug-in instead of the multi-toggle selection mode, the behavior for range selection and Select All changes:

By default, a dedicated Deselect All button replaces the Select All checkbox. There is no default UI element for selecting all items.
You can set a limit for the number of items that can be selected (sap.ui.table.plugins.MultiSelectionPlugin, property: limit). This limit has the following effect:
- The range that can be selected using the Shift key is limited to the specified number of items (default = 200). The table automatically scrolls back to the last selected item and you can display a corresponding message (sap.ui.table.plugins.MultiSelectionPlugin, property: enableNotification). Users can select more items by selecting additional ranges (the specified limit applies each time).
- If the selection limit is set to 0, a Select All checkbox is shown. There is also no limit on the number of items that can be selected in a range. All selected items are loaded, which can lead to performance issues for large data sets. (Keyboard: CTRL+A)
If selected items are not already available in the front end, they are loaded automatically by the plug-in and set as selected.

Information

When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size (sap.ui.table.Table, property: threshold) is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

A multiselection grid table

Using the multi-selection plug-in with a limit

Selection Behavior

An item can be selected in different ways, depending on the configuration of the grid table (sap.ui.table.Table, property: selectionBehavior):

Row: An item is selected by clicking the checkbox or the row. Use this option for multi-selection grid tables if clicking a row or a cell is not used for anything else.
RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this option if clicking the row (or a cell inside the row) is used for something else, such as navigation.
RowOnly: An item is selected only by clicking the row, and not using checkboxes in the selector cells. Use this for single-selection grid tables if clicking a row or a cell is not used for another purpose, such as navigation.

Compact, Cozy, and Condensed

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

For a desktop, you can also display even more rows on the same screen height by adding the condensed mode in addition to the compact mode. This renders less white space for each item.

Note that the condensed content density has always to be set in addition to compact. Do not use condensed on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable and / or unwanted results, e.g. cozy sized controls in condensed sized containers, missing paddings, etc.

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

Furthermore, condensed mode is not available for Internet Explorer 9. If condensed mode is to be used, please provide a fallback.

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

Column Header

The column header provides the label for the corresponding column and access to the column header menu.

Columns are resized as follows:

Mouse interaction: The user drags the separator line between two columns (sap.ui.table.Column, property: Resizable). Double-clicking the line optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable).
Touch interaction: The user taps the column header to reveal two buttons – one to show the column header menu, and one for resizing. The user drags the latter to resize the column.
Keyboard interaction: The width of the focused column header can be increased via Shift+Right and decreased via Shift+Left.

After resizing a column, the adaptation of the column widths depends on how the column width is set:

If column widths are set in pixel-based units (px, em, rem), the corresponding column is adapted and the columns that follow are moved accordingly. The width of all other columns is not affected.
If all the columns together take up less width than the table control, an empty space is added. In case all columns together take up more width than the table control, a scrollbar appears. (sap.ui.table.Column, property: width)
If all column widths are set in percentage or “auto”, resizing one column might also lead to the automatic resizing of some or all other columns. The position of the resized column might also be affected. This is done to ensure that the whole table width is used and no white space is added. A scrollbar appears only if all or most of the columns shrink significantly. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

Columns can be rearranged by dragging the column header to another position (sap.ui.table.Table, property: enableColumnReordering). Keyboard: the focused column header can be moved by one position in the corresponding direction via Ctrl+Left / Ctrl+Right.

Column header

Opening the column header menu on touch devices

Fewer columns than space available

Column Header Menu

For each column, a menu can contain the following menu items (sap.ui.table.ColumnMenu, property: visible):

Sort Ascending/Descending (sap.ui.table.Column, property: showSortMenuEntries)
Free text filter (sap.ui.table.Column, property: showFilterMenuEntries)
Freeze from the first to the last specified column (sap.ui.table.Table, property: enableColumnFreeze)

For each column, the menu can be replaced by an app-specific menu.

Column header menu

Sort

The column header menu can provide two sort options (sap.ui.table. Column, properties: sortProperty, showSortMenuEntry):

Sort Ascending
Sort Descending

The user selects one of these options to sort the corresponding column accordingly (sap.ui.table. Column, properties: sorted, sortOrder, sortProperty).

Sort settings in column header menu

Filter

The column header menu can provide a search field for entering free text (sap.ui.table.Column, properties: filterProperty, showFilterMenuEntries).

If the user enters a term in the input field and triggers the search by pressing Enter when the focus is on the filter input field, the grid table is filtered by the corresponding column and value (sap.ui.table.Table, properties: filtered, filterProperty, filterValue, filterOperator, sap.ui.table.Column, property: filterType).

Note that the filter may return zero results, in which case, the table might be empty.

General recommendations for filtering:

If filtering is a main use case, choose the filter bar or any other filtering UI over the built-in free text filter.
Only use the free text filter if filtering is a secondary use case and if the filter bar is too heavy.

Free text filter in column header menu

Freeze Columns

The column header menu can provide the option to freeze columns (sap.ui.table.Table, property: enableColumnFreeze). Selecting Freeze freezes all columns up to the one in which the operation was triggered (sap.ui.table. Table, property: fixedColumnCount).

When Freeze is triggered, the menu item changes to Unfreeze for the corresponding column.

Freeze setting in column header menu

Line Item Level

A line item contains a set of cells and provides options for selecting the item.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.Table, property: rowHeight).

Line item

Drag and Drop

One or several items can be repositioned within a table or moved to other UI elements using drag and drop operations (sap.ui.table.Table, aggregation: dragDropConfig). While being dragged, the items are shown as ghost elements on the mouse cursor.

Drop targets can be on items, between items, or both (sap.ui.core.dnd.DropPosition). On a drop target, the mouse cursor changes to either a “copy”, “link”, “move”, or “none” cursor. “None” indicates that the dragged item cannot be dropped in the current position (sap.ui.core.dnd.DropEffect).

Drag and drop is only available on supporting browsers.

Drag and drop

Whole item as drop target

Context Menu

You can attach a context menu (sap.m.Menu) to a table. The context menu gives users an alternative way to modify the focused elements by giving them access to context-specific functions.

When opened, the context menu gets the row and column context, except for special columns (such as the selection column) or special rows. Context menus can be implemented for a specific table, row, or cell (not recommended for editable cells).

Context menus are opened by right-clicking (desktop), long press (mobile), the context menu key, or Shift+F10.

Be aware that using the context menu overrides the browser context menu, which can no longer be opened.

If a control inside a table is the “click target”, and the control also provides a context menu, the control context menu “wins”.

Grid table with a context menu

Cell Level

A cell provides one data point and can contain one of the following controls:

Button
Checkbox
Combo box
Currency
Date picker
Icon
Input
Label
Link
The following micro charts size XS: Bullet, comparison, stacked bar
Multi-combo box
Multi-input field
Object status
Progress indicator
Rating Indicator
Select
Text
Use only single-line text to keep the same row height. Truncate it if necessary to prevent adverse side effects with vertical scrolling (sap.m.Text, property: wrapping, value: false). Do not wrap.

We recommend against using other controls to prevent issues with alignment, condensed mode, screen reader support, and keyboard support.

Cell

Guidelines

Data Density vs. Complexity

The grid table can be used to display large amounts of data. Unfortunately, the grid table has a high data density and therefore conveys an immediate feeling of complexity.

Only show tables with a lot of data as a last resort. Try the following instead:

Break down the data into manageable chunks and allow the user to navigate or drill down between them.
Use charts with drilldown functionality until the amount of data is more manageable.

Try to avoid horizontal scrolling in the default delivery.

Try to minimize the number of columns, especially if there is a large number of rows.

Table Title

Implement the table title by using a title control in a toolbar.

Use a table title only if the title of the table is not indicated in the surrounding area.

Do not use a table title if it simply repeats text that is already above the table. For example:

A pricing conditions table is the only control on a tab labeled Pricing Conditions.
A section or subsection on an object page contains only one table.

Use a table title if you need the item count, table toolbar, or variant management. To avoid repeating text, feel free to use generic text as a table title, such as Items.
Exception: If the surrounding area contains the table title, and both the item count and toolbar can be added to the surrounding area, no additional table title is needed.
Example: An object page (sub-)section contains only one table. In this case, add the item count and the table toolbar to the (sub-)section header.

If you use a table title, show either a title for the table, with or without variant management, or an item count in the following format:

Items (2,534).

The item count in the table title includes all the visible items that a user can reach by scrolling.

Remove the item count in the table title if there are zero items.

Developer Hint

Assistive technologies (such as screen readers) use the title to create a hierarchical site map for faster navigation. In addition, screen readers use the title as the label for the table.

If you don’t use a title (for example, to avoid repetition), make sure that the table is connected to another meaningful on-screen text that can be used as a label for assistive technologies. You can do this using the method addAriaLabelledBy.

Selection

Single Selection

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

Information

When setting a limit for the number of items that can be selected, keep the following boundaries in mind:

The performance of your service: How many items can be loaded at once in a reasonable time? Does this also apply if an end-user shows all available columns?
The “minimum limit”: Internally, the grid table loads blocks of items as the user scrolls down. Because this block size is usually also based on the performance of the service, it should be safe to assume that the minimum selection limit is twice this size. In this case, loading the data would take as long as scrolling down and loading exactly one more block. Nevertheless, we recommend using larger limits if your service allows.

In multiple selection mode (multi toggle), do not show checkboxes in the first data column in the default delivery to avoid confusion.

Don't

Do not add checkboxes to the first data column in the default delivery

Never disable the selection checkbox. If an action can’t be performed on a specific item, inform the user after the corresponding action has been triggered. For more information, see Enabling/Disabling Actions.

Loading Data

To indicate that the table is currently loading items, use the busy state. (sap.ui.table.Table, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Grid table in busy state while loading data

Errors and Warnings

To indicate that the table contains items with errors or warnings, show a message strip above the table. On the message strip, provide information about errors or warnings. When issues are solved or when new issues appear, update the message strip accordingly.

To indicate an error in a single row, see Item States below.

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

Developer Hint

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

Table containing errors and warnings

Columns – Best Practices

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

The grid table assigns the same width to each column by default. It is recommended that you overwrite this default to provide optimal space for your content (sap.ui.table.Column, property: width).

If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the browser window size results in a scrollbar. After resizing a column, a scrollbar appears if the width of the table is not enough to show all columns. If the columns use less space than available, white space appears on the right side of the last column.

If you define the column width as a percentage, resizing one column affects the width of several or all columns. Text becomes truncated when the browser window size is reduced. This is done to make sure that all columns together fill the space of the table. A scrollbar appears only in case the automatic change of the column widths is not enough for showing all columns. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum.

If you define the column width as “auto”, the behavior is the same as for “percentage”. In contrast to percentage, “auto” distributes the columns equally.

To decide on how to set the column width (pixel / rem / em vs. percent / auto), keep the following in mind:

For tables with only 2 to 3 columns, use pixel-based units. This ensures that on wide screens the values in the columns are not spread over the whole screen, which improves the readability of line items.
For tables with many columns, where a horizontal scrollbar is usually needed, use pixel-based units. This avoids unintended side effects when resizing columns.
For all other tables, use whatever fits your case better.

Be cautious with mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it could also cause even more unexpected side effects when resizing a column. When using percentage-based widths for one or more columns, think of the possibility to not allow end users to resize columns at all.

Optimize the column width for its initial visible content, including the column header texts. If this is not possible (for example, if showing the full texts would result in extremely wide columns), let the texts truncate. End users can change the width of the column to read the full text, as needed.

Maintain a constant column width and avoid adjusting it automatically when the content changes.

Always keep to one line of text. Do not wrap.

Don't

Don't truncate the initial visible content in the default delivery

Don't

Never wrap texts

Column Headers – Best Practices

For each column, provide a label in the column header. In the default delivery, do not truncate the column header texts. Only let the text truncate if showing the full text would make the column too wide. Never wrap the text.

Content Alignment

For alignment of cell content, follow the guidelines below.

Left-align the following: text, IDs, phone numbers, URLs, passwords, and email addresses.

Left-alignment of text

Right-align numbers (except IDs).

This ensures comparability of numbers and amounts.

Right-alignment of numbers

Right-align amounts with currencies to the cell and align them in terms of their respective decimal points.

This ensures that amounts with different currencies are shown correctly, whether these currencies have 0, 2, or 3 decimals.

For aligning to the decimal point, use the sap.ui.uinified.Currency control.

Alignment to decimal point

Right-align dates and times.

This ensures comparability for most formats and locales.

Right-alignment of dates

Left-align status information.

Left-align status information

Center-align icons.

Left-align micro charts.

XS micro charts in condensed mode

Content Formatting

Locale Settings

Be locale-aware: show dates, times, numbers, and so on in the format corresponding to the user’s locale settings.

Key Identifier

Use a bold label or an emphasized link as the key identifier of an item. In the default delivery, show the key identifier in the first column.

Emphasized link

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.

Text and ID in two columns – Allows users to sort and filter both separately

If displayed as a link, use only the text as the link, not the ID

Text and ID in one column – Sorting and filtering is available for either the text or the ID, but not for both

Text and ID in one column - If displaying a link, show the whole string as the link (text and ID)

Truncation

Avoid truncation of typical content in the default delivery (sap.ui.table.Column, property: width). However, since the columns are resizable, do not worry too much if truncation occurs as columns can still be enlarged if necessary.

To prevent adverse side effects when scrolling vertically, all line items must also have the same height. If you need to decide between truncation and different row heights, choose truncation. Do not wrap.

Optimize column width for typical content, not all content

Number of Links

Are there too many links? Use subtle links to avoid a wall of links. Standard links are also emphasized more if they are surrounded by subtle links.

Emphasized links, links, subtle links, and text

Missing Value

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

Leave empty fields blank

Numbering Items

In terms of numbering items:

If the item number is more like an ID with regard to its description, use ID formatting as described above.
In all other cases, use a separate column for the item number.

Add a separate column for the item number

Status

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

For status information on text, use an object status.

Semantic colors on text

Micro Charts

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

Micro charts in a grid table

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

Provide meaningful instructions

Invalid State

To show an invalid state of the grid table within the list report floorplan, show an overlay on the grid table and the corresponding toolbar (sap.ui.table.Table, property: showOverlay). The overlay prevents user interactions.

Use this within the list report floorplan if filter settings have been changed but the grid table is has not yet been updated.

Grid table with invalid data

Item States

To show that an item has been modified, for example, within the global edit flow, add the string Modified in an additional column with the label Editing Status.

In the default delivery, add a column directly behind the key identifier.

A modified item

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.

A modified item with an error

To show that an item is locked, add a transparent-style button with the corresponding icon and the text Locked by [name] in the Editing Status column.

A locked item

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

Item in draft state

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 of measurement in one cell

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.

Number and unit of measurement in two columns

Show the unit of measurment on the column header, if the unit of measurement is the same for all rows. If not, show the unit of measurement within the row.

Drag and Drop

If you offer drag and drop for rearranging items within the table, use drop targets that are between items (sap.ui.core.dnd.DropPosition.Between). This provides better feedback on where the item will be inserted. Show the “move” mouse cursor (sap.ui.core.dnd.DropEffect.Move).

Drop targets in between items

Do not combine rearranging items and sorting. If you really need to do so, make sure that there is a dedicated sort criterion for the user-defined sort order, and only offer options for rearranging items if this sort order is set.

Don't

Do not combine rearranging items with sorting

Drag and drop is “invisible” on the UI: users can’t see where dragging is available and where it isn’t. In addition, there is no generic keyboard interaction. Drag and drop is also not available on all browsers. For these reasons, provide it only in addition to existing (and visible) UI elements that fulfill the same purpose. For example, offer (toolbar) buttons for moving or for copying and pasting items. These are keyboard operable and available on all browsers.

Use drag and drop only in addition to existing visible UI elements

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.

Navigate to details page

Single Cell

To trigger actions on a single cell, create the corresponding click event. Do not use the cell click event if the cell contains interactive controls, such as links.

Add Items

For adding items, place an Add or Create text button on the table toolbar.

Use Create if the button adds a brand new item that doesn’t yet exist on the database.
Use Add if the item already exists and is merely added or assigned to the current object.

Show new items as the first item of the table, with a visual highlight at the beginning of the row.

Enable the shortcut Ctrl+Enter (and ideally Enter in addition) to trigger the Add or Create button.

There are three options for adding an item. In order of priority (most recommended first), these are:

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.
Open a dialog for larger tables with up to 8 editable columns. Save the new item at dialog level.
Navigate to a new page. This behavior should only be used for very complex scenarios that cannot be handled by a dialog (for example, 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

For editable content, only use the following controls, and only one control per cell:

Only these controls are optimized for all viewing modes of the grid table.

If you need edit mode, change your text controls, such as label, text, link, object status, icons, and currencies, to editable controls as soon as you switch to edit mode, but not before. You can do this by exchanging the controls, for example, from sap.m.Text to sap.m.Input.

For mass editing items:

Provide multiselection.
Provide an Edit button.
If several items are selected, clicking the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

For more information, see Mass Editing.

Interactive controls – In line

View Settings

There are several ways to show Sort and/or Filter settings:

Column header menu: In all cases, show the corresponding settings in the column header menu.
View settings dialog: Simple and more flexible with regard to filter settings. No advantage for sorting.
Table personalization dialog: Provides complex options for sorting items by several levels. It also provides a query-builder-like approach for filter settings. The complexity of the options is also its downside. Use the table personalization dialog for tables with a large number of items.
If filtering is a main use case, use the filter bar. In this case, avoid offering additional filter settings on the table. If you do, the filter settings on the grid table work only on the result set provided by the filter bar.

Always be careful when synchronizing the settings in the dialog with the settings from the column header menu.

Trigger the dialogs in one of the following ways:

View settings dialog: Provide several buttons, one for each of these view settings. Each button opens the view settings dialog on the corresponding page.
P13nDialog: Provide a settings button, which opens the table personalization dialog containing all pages.

Use only the view settings you really need.

Column header menu with view settings

Table toolbar with triggers for view settings dialog

Table toolbar with trigger for table personalization dialog

Persist the user settings: When reopening the app, show the grid table with the same sort and filter settings as last defined by this user.

Sort

Always sort the table in a meaningful way when it first loads. In most cases, this means sorting by the column that identifies the row. This is usually the first column in the default delivery.

To display the current sort state, an icon is shown in the column header of the most recently sorted column. This icon indicates the sort direction (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

For the default sort settings, sort by the column that identifies the row, which is usually the first column in default delivery.

Column, sorted ascending

Column, sorted descending

The descending sort order must always be the exact reverse of the ascending sort order. For each column, provide a meaningful sort order. For example:

Sort text alphabetically
Sort numbers by their value
Sort status information by the severity of the status:
- Ascending: Sort status information from positive to negative, with neutral last.
- Descending: Sort status information from negative to positive, with neutral first.

Object status sorted ascending, with neutral status last

Object status sorted descending, with neutral status first

- Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
- Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Object status sorted ascending and alphabetically, from positive to negative with neutral last

Object status sorted descending and alphabetically, from negative to positive with neutral first

Filter

To display the current filter state, an icon is shown in the column header of the filtered column (sap.ui.table.Column, properties: filtered, filterProperty, filterValue, filterOperator, defaultFilterOperator, filterType).

Column, filtered

Personalization

Only offer personalization if you need more columns than those that fit on a tablet screen, which is usually five, to fulfill 80% of your main use cases.

Persist the column layout. When a user reopens the app, show the grid table with the same column layout settings as last defined by this user.

Add, Remove, and Rearrange Columns

To add, remove, or rearrange columns, use one of the following:

The table personalization dialog: It offers some simple settings for column layout. Use this if you have only a few columns to choose from and/or you use the view settings dialog.
The p13n dialog: Besides various complex view settings, it also provides settings for column layout. Use this if you have a large number of columns to choose from and/or you use this dialog anyway for view settings.

In both cases, trigger the dialog via the settings button in the table toolbar. As short cut, use Ctrl+comma.

You can also use drag and drop to rearrange columns (sap.ui.table.Table, property: enableColumnReordering). If you allow rearranging via drag and drop as well as via a dialog, keep both places in sync.

Resize Columns

Resizing columns works differently on touch and non-touch devices.

Non-touch devices: Drag and drop the column separator on the right side of the column. Double-clicking the column separator optimizes the width of the column to the data currently loaded into the front end, which is usually about 100 rows.
Touch devices: Clicking the column header reveals two buttons: one for opening the column header menu, another one for resizing the column. Drag and drop this second button to resize the column.

Freeze Columns

To freeze columns, offer the setting in the column header menu (sap.ui.table.Table, property: enableColumnFreeze). Selecing Freeze on a column freezes all columns from the first one to the one where Freeze is selected. On this column, the menu entry changes from Freeze to Unfreeze.

Frozen column

Highlight Items

To show that an item needs attention, a highlight indicator can be shown in front of the item. The highlight indicator can be used to indicate:

A semantic state, such as red or orange for an error or warning. In this case, use semantic colors.
Additional information, such as blue to highlight newly added items. In this case, use semantic colors.
Industry-specific or process-specific states, such as “out of stock” or “excess of inventory”. In this case, use indication colors.

Be aware that the highlight is just an indication. It does not tell users exactly what is wrong. Make sure that you provide this information within the table row, ideally in the same color.

For details on the use of highlight colors, see How To Use Semantic Colors / Industry-Specific Colors.

(sap.ui.table.Table, aggregation: rowSettingsTemplate)

Highlighted items

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.

'Export to Spreadsheet' menu button

Paste

The browser paste function can be used to paste data from the clipboard to the table (Ctrl+V or browser context menu).

If the focus is on row level, the app has to take the data from the clipboard and add it to the corresponding controls within the table.
If the focus is on an editable control within the table, the control gets the data automatically.

Pasting via the context menu does not work if a custom context menu is used.

Properties

sap.ui.table.Table

The following additional properties are available for the grid table:

The property: width defines the width of the grid table.
The property: rowHeight defines the height of each row in the grid table. Since the height required is calculated automatically by the grid table, this property is only needed rarely.
The property: columnHeaderHeight defines the height of the column headers. Since the height required is calculated automatically by the grid table, this property is only needed rarely.
The property: columnHeaderVisible can be used to hide the column headers. Always show the column headers.
The property: showColumnVisibilityMenu provides an additional entry in the column header menu that allows columns to be shown or hidden. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
The property: visibleRowCount defines the height of the grid table. Show as many rows as fit on the screen.
The property: visibleRowCountMode defines whether the height of the grid table is fixed or automatically calculated based on the space provided by the underlying container. For automatic calculation, make sure that all rows have the same height.
The property: minAutoRowCount defines the minimum number of rows that must be shown if the property: visibleRowCountMode is set to “auto”. Show at least three to five rows.
The property: firstVisibleRow defines the first row shown in the visible area of the grid table. The grid table is scrolled accordingly.
The property: allowColumnReordering is deprecated. Do not use it. Use the property: enableColumnReordering instead.
The property: editable does not have a visible effect. Do not use it.
The property: enableCustomFilter changes the filter entry in the column header menu from an edit box to Filter…. Selecting this entry throws an event to which apps can react, for example, by opening a dialog. In general, you should choose the built-in filter over your own implementation. Specifically, keep filtering via the column header menu simple, while offering more advanced options via the table personalization dialog.
The property: enableBusyIndicator has not yet been fully implemented. Do not use it.
The property: title adds a line of text on top of the grid table. Do not use this. To add a title to the table, use a toolbar.
The property: footer adds a short text at the bottom of the table.
The property: Busy sets the grid table to busy state. While in busy state, the whole table cannot be used and items cannot be read due to an overlay.
The property: Tooltip does not have an effect. Do not use it.
The property: alternateRowColors displays the rows with alternating background colors (“banded rows”). Do not use it.

sap.ui.table.Column

The following additional properties are available for the column:

The property: visible defines whether a column is shown or hidden.
The property: name defines the name shown in the column header menu for showing and hiding columns. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
The property: headerSpan defines whether one column header is used for one or several columns. To prevent adverse side effects, always use one column header for only one single column. Do not use this property.
The property: Tooltip does not have an effect. Do not use it.

sap.ui.table.Column

The following additional properties are available for the column:

The property: visible defines whether a column is shown or hidden.
The property: name defines the name shown in the column header menu for showing and hiding columns. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
The property: headerSpan defines whether one column header is used for one or several columns. To prevent adverse side effects, always use one column header for only one single column. Do not use this property.
The property: Tooltip does not have an effect. Do not use it.

Resources

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

Elements and Controls

Analytical Table (guidelines)
Bullet Micro Chart (guidelines)
Comparison Micro Chart (guidelines)
Feed List Item (guidelines)
Link (guidelines)
List Report Floorplan (guidelines)
Multi-Input Field (guidelines)
Responsive Table (guidelines)
Stacked Bar Micro Chart
Table Personalization Dialog (guidelines)
Table Toolbar (guidelines)
Tree Table (guidelines)
Variant Management (guidelines)
View Settings Dialog (guidelines)

Implementation

Column (SAPUI5 API reference)
Column Menu (SAPUI5 API reference)
Grid Table (SAPUI5 API reference)
Grid Table (SAPUI5 samples)

Smart Field

The smart field creates different user input controls and their read-only equivalents based on an OData (Open Data Protocol) service and its annotations. It comes with additional built-in features, such as autocomplete and suggestions, value help dialog, recently used and recommended values, validation, and message handling.

Information

The smart field is only available for OData version 2.

When to Use

Use the smart field if:

You use an OData service for your app (OData version 2 only).
The feature set of the smart field fits your app. In this case, the smart field is faster to implement.
You use the smart table and your app is not performance-critical. The smart field offers more flexibility than the controls provided directly by the smart table, especially for editing.
You use a smart form.

Do not use the smart field if:

You use a different technology to OData version 2. Use the corresponding controls directly.
You need a different control for entering or displaying data, such as multi input, a multi combo box, step input, a radio button, or a title. In this case, use the corresponding control directly.
You need a different dialog for offering value help, such as the select dialog or table select dialog.
You use the smart table and your app is performance-critical. In this case, the controls offered directly by the smart table offer less flexibility but better performance.

Components

The smart field consists of a basic UI element and an optional label. The following UI elements are available:

Edit mode:

One or two input fields (with or without a value help dialog)
Select
Combo box
Text area
Checkbox
Date picker
Date/time picker
Time picker

Display mode:

For details, see the corresponding guideline topics.

User Input Control

The smart field chooses the control automatically based on the data type (Edm type) and annotations of the OData service and additional properties. The following controls are used:

	Read-Only	Edit	Edm Types / Annotations / Properties	Comment
Single-line text	Text	Input field	Edm.String Configuration: controlType, value: input
		Combo box	Edm.String Configuration: controlType, value: dropDownList
		Select	Edm.String Configuration: controlType, value: selection
Multi-line text	Text	Text area	Edm.String MultiLineText
Decimal numbers	Text Object number	One or two input fields (for number and unit)	Edm.Int16, Edm.Int32, Edm.Int64, Edm.SByte, Edm.Byte, Edm.Single, Edm.Float, Edm.Double, Edm.Decimal Precision, Scale
Status information	Object status		Edm.String criticality, criticalityRepresentationType
Text and ID	Text Object identifier Object status	Input field	TextArrangement controlProposal displayBehavior textInEditModeSource, sap:text, fetchValueListReadOnly	The following patterns can be selected via displayBehavior: Text (ID) ID (Text) Text ID
Links (with/without quick view)	Link Smart link		Edm.String IsURL, url semanticObjectController
Dates	Text	Date picker	Edm.DateTime sap:display-format=”Date” IsCalendarDate Configuration: controlType
Dates and times	Text	Date/time picker	Edm.DateTime Edm.DateTimeOffset
Times	Text	Time picker	Edm.Time
Fiscal periods	Text	Input field	IsFiscalYear, IsFiscalPeriod, IsFiscalYearPeriod, IsFiscalQuarter, IsFiscalYearQuarter, IsFiscalWeek, IsFiscalYearWeek, IsDayOfFiscalYear
Amounts with currencies	Text	One or two input fields	ISOCurrency or sap:unit with sap:semantics=”currency-code”
Phone numbers	Text	Input field	IsPhoneNumber
Email	Text	Input field	IsEmailAddress
Boolean	Checkbox	Checkbox	Edm.Boolean
Boolean	Text	Combo box	Edm.Boolean valueList displayBehavior	The text in display mode can be influenced via displayBehavior: Yes/No True/False On/Off

Guidelines

Set a default value whenever appropriate (annotation: text, property: value).
To show a static unit of measurement, use a description (annotation: text).
To display a text and ID in the same place, use the format Text (ID) wherever possible. Use another format only if displaying the text doesn’t make any sense. Be careful when using the text arrangement options in tables: end users will only be able to sort, group, or filter based on the ID, even if the ID isn’t visible.
If you are not using the smart field within a smart form or smart table, label the smart field with a smart label (annotation: label, properties: textLabel, showLabel). The standard label doesn’t know the inner structure of a smart field.
You can set a tooltip (annotation: QuickInfo), but this should usually be avoided. See Using Tooltips.
If data entry is expected in a specific format, set a placeholder (property: Placeholder).

Developer Hint

Performance: Using the TextArrangement annotation to display both the text and ID (in any order) triggers two requests to the back end.

Behavior and Interaction

Context

You can use the smart field in different contexts
(property: controlContext):

Standalone
Within a form (depending on the form layout)
Within a table (depending on the table type)

The context influences:

Labels: In most cases, forms provide the label automatically.
Empty values in display mode: In forms, empty values are shown as a dash. In tables, the field remains blank. In popins, empty values are shown as a dash because the popin is similar to a form in a table.
How units of measurement are displayed

Guidelines

If the width is not handled by the context, set a meaningful width for the smart field, based on the expected data (property: Width).
If you use a “standalone” smart field in a form-like arrangement, use a dash to show an empty value in display mode.

Switching Between Edit and Display Mode

Switching between edit and display mode can be controlled manually (annotation: FieldControl, property: editable) or automatically by the containing smart form or smart table (property: contextEditable).

Smart field as a select with 'required' indicator in edit mode

The same smart field in display mode

Guidelines

Define which fields should be editable (annotations: updateable, creatable, updateable-path, InsertRestrictions, UpdateRestrictions, computed, immutable, fieldControl, fieldControlType).
For fields with a unit of measurement, define whether the unit of measurement is editable or static (annotation: FieldControl, property: uomEditable).
Make sure that the full text is shown in display mode (property: wrapping), unless this is handled differently for the corresponding context (for example, see guidelines for content in the grid table).
When you display the text and ID, the smart field automatically displays both values in display mode, but only the ID in edit mode (annotation: TextArrangement). In most cases, it makes sense to also display both values in edit mode (annotation: sap:text, property: textInEditModeSource, aggregation: Configuration with property: displayBehavior).

Suggestions and Value Help

You can enable suggestions for controls that offer this feature (property: showSuggestions). The list of suggestible values must be provided (annotation: ValueList or ValueListWithFixedValues only for Edm.String, property: entitySet). This list can contain several attributes and is also used for the value help dialog. You can restrict the number of attributes from this list to be shown as suggestions, while all attributes are shown within the value help dialog.

Autocomplete is enabled automatically.

For input fields, the value help dialog is also created automatically. Hide it if it is not needed (property: showValueHelp). The table in the value help dialog can be filled with initial content (annotation: ValueList, property: fetchValues, sap.ui.comp.smartfield.Configuration, property: preventInitialDataFetchInValueHelpDialog)

Both the value help dialog and the suggestion list can be prefiltered (annotation: ValueList, property: valueListParameterIn). The selected items can be used to prefilter other fields (annotation: ValueList, property: ValueListParameterOut). The corresponding filter settings are visible. “Invisible” prefiltering is also supported. To use this option, provide the exact matching filter value (Common.ValueListParameterConstant).

If a value has been entered in the smart field, this value is transferred to the search field of the value help dialog automatically. In the value help dialog, individual values can be valid, deprecated, or revoked. Revoked values are hidden from the value help (annotation: IsConfigurationDeprecationCode).

The following controls are used to offer suggestions or value help:

A fixed value list leads to a combo box or select, depending on the control configuration.
A non-fixed value list leads to an input field with a value help dialog.

Smart field as a combo box

Smart field as an input field with suggestions, auto complete, and a value help button

The automatically generated value help dialog for the same smart field

Recently Used Values

Input fields, combo boxes, and selects can provide up to five recently used values automatically on focus if suggestions or value help are available. This can be turned on or off per field (property: historyEnabled). Recently used values are shown by default for input fields, but not for combo boxes and selects.

Guidelines

Do not show recently used values for a field if:

There are only a small number of options.
The field contains personal sensitive data (annotation: IsPotentiallySensitive).
It is unlikely that the same values will be selected again and again.

Recommended Values

In addition to recently used values, a smart field can show recommended values (annotation: RecommendationState).

The corresponding smart field is highlighted and/or prefilled:

If no recommendation is available or the current user input matches the recommendation, the smart field is shown in the default state.
If a recommendation is available and there is no user input, the smart field is shown in the information state.
If a recommendation is available and it differs from the current user input, the smart field is displayed in the warning state.

The recommended values are shown as soon as the user focuses on the smart field.

Validation

The smart field offers the following validations automatically:

Validation for required fields: This can be done on the client or server side (property: clientSideMandatoryCheck, annotation: Nullable).
Validation for a group of fields: Validation is triggered when the focus moves outside a group of fields, rather than when a single field loses the focus. A group is defined by all smart fields that share the same field group ID (property: fieldGroupIds).
Validation for the maximum length of user input: Validation is triggered when a field loses the focus or the ENTER key is pressed (property: maxLength).
Validation for combo boxes: Checks if the value entered is available in the dropdown list (property: fixedValueListValidationEnabled).

The validation result is indicated by a value state (property: showValueStateMessage).

When the user edits a smart field showing a text and ID, you can allow any kind of input to avoid unnecessary validation issues (annotation: ValueListNoValidation).

Examples:

Allowing the user to enter additional values (which are not in the suggestion list)
Typing a text instead of an ID to filter down the suggestion list
Using the smart field in a draft

Automatic validation

IDs

The smart field offers automatic validation for number-only ID fields (annotations: IsDigitSequence or sap:display-format="NonNegative"):

It checks for non-negative numbers.
It shows values containing only “0” digits as empty.
It does not show leading zeros.

Units

For decimal number fields and for fields that show an amount with a currency, you can add a unit of measure (annotations: unit, sap-unit with sap:semantics="unit-of-measure" or sap:semantics="currency-code", property: uomVisible). In display mode, the unit is added to the corresponding number. In edit mode, the unit is shown either as text or, if editable, as a second input field (properties: uomEditable, uomEnabled).

Smart field showing an amount with a currency in display mode

The same smart field in display mode

Sensitive Data

Sensitive data, such as passwords, can be masked. The text is then replaced with asterisks (annotations: IsPotentiallySensitive, masked).

Capitalizing Text Input

Text input can be capitalized automatically (property: IsUpperCase).

States

Smart fields support the following states (annotation: fieldControl):

Editable or display only (additional annotations: updateable, creatable, updatable-path, InsertRestrictions, UpdateRestrictions, property: editable)
Enabled or disabled
Visible or hidden (additional annotations: property: visible, annotation: sap:visible)
Required: If set, the smart field must contain a value when validated. This is indicated by an asterisk next to the corresponding label (additional annotation: Nullable, property: mandatory).

The following states for a unit of measurement can be set independently of the corresponding field:

If editable, a unit of measurement can be enabled or disabled (property: uomEnabled)
The unit of measurement can be visible or hidden (property: uomVisible)

Developer Hint

In the SAPUI5 SDK API Reference for the smart field, the display only state is referred to as read only.

Dependencies between Smart Fields

If the content of a smart field is changed, you can trigger additional changes to other fields on the UI (annotation: SideEffects).

Content Alignment

You can change the horizontal alignment of the text within any kind of input field (property: textAlign).

Guidelines

Follow the alignment rules for the respective context (responsive table, other tables, form). If you are using the standalone option for the smart field (without a context), apply the rules for the corresponding input fields.

Responsiveness

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

Top Tips

Always label a smart field if it is not inside a table context.
Use suggestions with autocomplete whenever possible and meaningful.
- Do not show suggestions if there are only a few choices.
- Use recently used values as appropriate.
- Reduce the number of attributes shown in the suggestion list to a maximum of 4 or 5.
Make use of validation features.

Properties

The following properties, aggregations, and associations are available for sap.ui.comp.smartfield.SmartField:

The property: expandNavigationProperties is deprecated. Do not use it.
The property: importance hides the field if the smart field is placed in a smart form, depending on the importance setting of the smart form. End users have no possibility to show the corresponding fields again. Do not use this property.
The property: jsontype is deprecated. Do not use it.
The property: name is used in HTML forms that send data to the server via “Submit”.
The property: uomEditState is for internal use only. Do not use it.
The property: proposedControl is deprecated. Do not use it.
The property: textDirection provides support for reading directions in different locales.
The aggregation: controlProposal is deprecated. Do not use it.
The association: ariaLabelledBy can be used for linking additional labels to the smart field.

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
The table content should be flexible and visually appealing. The responsive table offers the most flexibility for its content because all SAPUI5 controls, and even multiple controls, can be used. In addition, different rows can be based on different item templates.
The users focus on line items, not on individual cells.
A main use case involves selecting one or more items, and users need details to select them correctly.
Line items are independent of each other and no operation across columns is needed.
You want to have only one implementation for all devices. Make sure you adapt the responsive table design to offer the best solution for mobile devices.

For more information, see the responsive table control.

Use the list if:

You want to display a simple dataset.
A table would be too complex.
A list of actions is to be displayed.
Simple two-level hierarchies are required (by using grouping or navigation).
The main use case involves selecting one of several items based on only a few details.
You require a list for a list-detail scenario using the flexible column layout.

For more information, see the list control.

Use the tree if:

You want to display a simple hierarchical dataset.
You want to use a hierarchical list for a list-detail scenario using the flexible column layout.
Using a tree table would be too complex.
The main use case involves selecting one of several hierarchical items based on only a few details.

For more information, see the tree control.

Use the grid table if:

You need a table to display a large amount of complex data. The grid table is optimized for scenarios that require large amounts of complex data to be loaded to the table. The number of items in the database or the filtered results are irrelevant.
The cell level and the spatial relationship between cells are more important than the line item, such as if users need to recognize patterns in the data, like in waterfall charts.
Comparing items is a major use case. The grid table layout remains stable irrespective of the screen width. In addition, a cell only ever contains one control.
The sequence of the items in the table is important.
Your use case is for tasks performed on desktop and tablet devices.

For more information, see the grid table.

Use the tree table if:

Data needs to be displayed in a hierarchical manner.

For more information see the tree table.

Use the analytical table if:

You need multilevel grouping as well as grand totals and subtotals.

For more information, see the analytical table.

Responsiveness

Fully Responsive Tables

The fully responsive tables adjust their appearance to the to the screen size so you can use it on all devices.

Make sure you design the best responsive table solution for the tasks performed on each device type. Sometimes, a solution without a table is more useful and useable for mobile devices.

Desktop-Centric Tables

The desktop-centric tables are not fully responsive, but available for only desktops and tablets, and they support 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.

Types

Fully Responsive Tables

Guidelines

Always consider ways to reduce the amount of data loaded in the responsive table with, for example, filters, graphics, aggregation of information, and navigation.

Keep in mind that you should use the responsive table only to display moderate amounts of data, including factors like number of items and content complexity.

Responsive Table (sap.m.Table)

Based on the list, the responsive table provides:

An optimized view of a line item at a glance without any horizontal scrolling, regardless of the screen width.
Full flexibility for table content:
- Any SAPUI5 control can be used in a cell, including micro charts and forms.
- Using layout containers, such as a grid layout, allows more than one control to be used in a cell. Consequently, the cell shows more than one data point.
- Templates with multiple rows are supported, so different items can have different layouts. For example, this can be used to show editable items and read-only items in the same table without switching modes. In this case, the editable items could have a completely different layout than the read-only items.
- Items with different heights are supported. This allows for more dynamic content in cells, for example, to show lists or use text controls that wrap instead of truncate.
Smooth scrolling. This is done by rendering all items on the application background. Thus, the responsive table does not have its own scrollbar but uses the scrollbar for the whole page.
A very lightweight design.
Touch interaction support.

Responsive table

List (sap.m.List)

The list is the basis for the responsive table. It should be used whenever a table is too complex.

The list provides:

Full flexibility in regards to its content:
- There are various specializations for specific list types.
- With a custom list item, all SAPUI5 controls can be used inside a list. Using layout containers allows more than one control to be used in a custom list item.
- Templates with multiple rows are supported, so different items can be shown in the same list.
- Items with different heights are supported.
Smooth scrolling. This is done by rendering all items on the application background. Thus, the list doesn’t have its own scrollbar but uses the scrollbar for the entire page.
A very lean and lightweight design.
Touch interaction support.

List

Tree (sap.m.Tree)

The tree is based on the list. It should be used whenever a hierarchical view is needed, but a tree table is too complex.

The tree provides:

A standard tree item that provides an icon, a text (that wraps), and a counter.
Support for items with different heights.
Smooth scrolling. This is done by rendering all items on the application background. Thus, the tree doesn’t have its own scrollbar, but uses the scrollbar for the entire page.
A very lean and lightweight design.
Touch interaction support.

Tree

Desktop-Centric Tables

The following tables belong to the desktop-centric table group:

Grid table: This is the most basic table in this group.
Analytical table: This provides the following features on top of the grid table:
- Grouping by several levels.
- Automatic calculation of grand totals for a column and subtotals per group level.
Tree table: This provides a hierarchical view of the items.

The desktop-centric tables have the following limitations:

Content layout is less flexible:
- The grid table supports only certain controls, mainly for displaying text or getting single-line text input from users. For example, you cannot add micro charts.
- Only one control can be added per cell.
- It supports only single-row templates.
- All items need to have the same height.
Vertical scrolling is not smooth. For performance reasons, the content is not really scrolled but exchanged.

Grid Table (sap.ui.table.Table)

The grid table provides:

An optimized way to show large amounts of data. It supports an unlimited number of rows. It also supports a very condensed display of line items on non-touch devices, thus allowing more rows to be displayed on the same screen property.
Fixed control height, thus supporting horizontal and vertical scrolling (“viewport scrolling”). However, this also means that there are several vertical scrollbars on the screen for the page and table, which might be cumbersome on smaller screens.
Touch interaction supported.

Grid table

Analytical Table (sap.ui.table.AnalyticalTable)

The analytical table is based on the grid table and is therefore quite similar to it.

In addition to the grid table, the analytical table provides:

Multilevel grouping
Display of grand totals per column and subtotals per group

Developer Hint

The analytical table needs analytical binding.

Analytical table

Tree (sap.m.Tree)

The tree table is based on the grid table and is therefore quite similar to it.

In addition to the grid table, the tree table provides:

One hierarchical column

Tree table

Resources

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

Elements and Controls

Responsive Table (guidelines)
List (guidelines)
Tree (guidelines)
Grid Table (guidelines)
Analytical Table (guidelines)
Tree Table (guidelines)

Implementation

Responsive Table (SAPUI5 samples)
List (SAPUI5 samples)
Tree (SAPUI5 samples)
Grid Table (SAPUI5 samples)
Responsive Table (SAPUI5 API reference)
List (SAPUI5 API reference)
Tree (SAPUI5 API reference)
Grid Table (SAPUI5 API reference)
Analytical Table (SAPUI5 API reference)
Tree Table (SAPUI5 API reference)

Which Selection Control Should I Use?

Selection controls are UI elements that allow the user to pick one or several values or options. Different selection controls are available, which each support dedicated use cases. This article offers guidance on when to use the following selection controls:

Selecting a Single Value or Option

To enable users to select a single value or option, display either a combo box, an input field, or a select control. A value is usually a single data point, while an option can consist of several data points, such as product attributes.

Combo Box

The combo box allows users to select one value/option from a predefined list. It’s also possible to type in a value or custom value and filter the predefined selection list (if the application allows it).

Combo box with two-column layout and option to enter custom value

Input Field

The input field allows users to enter and edit text or numeric values in one line. To help the user enter a valid value, you can enable the autocomplete suggestion feature or provide a selection dialog.

The selection dialog opens when the user clicks the input field icon.

Input field

Input field with a button to open one of the selection dialogs

Select

The select control (also known as a dropdown) is commonly used to select a value/option from a predefined list.

Select control

Selecting Multiple Values or Options

The multi-combo box and multi-input field support the selection of multiple single values or options. A value is usually a single data point, while an option can consist of several data points, such as product attributes.

Multi-Combo Box

Use the multi-combo box if users need to select multiple values/options from a predefined list. The values/options in the list have checkboxes that support multi-selection. Users can also type in a value to filter the list (if the application allows it).

Multi-combo box with three selected values

Focused, opened multi-combo box

Multi-Input Field

A multi-input field allows users to enter more than one value/option which are are displayed as tokens. You can enable the suggestions feature or provide a selection dialog to help users enter a valid value/option.

Multi-input field with three values

Multi-input field with three values while typing

Multi-input field with values and the option to open a selection dialog

Supporting Selection Dialogs

There are three selection dialogs: the select dialog, the table select dialog, and the value help dialog. These dialogs enable users to pick one or several values or options from a long list. Selection dialogs are useful when users need more than one data point to identify the “right” value/option, or when they want to search the list to find a particular value/option.

The selection dialogs are always used in combination with one of the following controls:

Input field for selecting one value/option
Multi-input field for selecting more than one value/option

Users can open the respective selection dialog from within these controls.

Example

The user wants to pick a certain product. However, because the product names are very similar, it’s difficult to identify the right one. Additional product attributes in the selection dialog, such as an image and the product release date, help the user to pick the correct option.

Select Dialog

The select dialog enables users to select one or more values/options from a comprehensive list. The select dialog comes with a list of entries containing a few attributes. It also provides a search field to filter the list.

Select dialog with two selected items

Table Select Dialog

The table select dialog enables users to select one or more values/options from a comprehensive table. Usually, the table displays multiple attributes or other related information for an item. Making this additional information available for an entry helps users identify the correct value/option.

The table select dialog reuses the responsive table. It also provides a search field to filter the list.

Table select dialog with two selected items

Value Help Dialog

The value help dialog enables users to find and select single and multiple values/options. It also allows users to define conditions and multiple ranges.

Value help dialog on a mobile device

Best Practices

Depending on the number of entries in the selection list, users might need more information to identify the “right” single value/option or multiple values/options.

Use the criteria in the tables below to choose the most suitable selection control according to the number of data points you have for each value/option and the number of entries you have in the selection list.

Selecting a Single Value or Option

The user can identify the “right” value/option based on…	2-12 entries in the selection list	13-200 entries in the selection list	200-1,000 entries in the selection list	More than 1,000 entries in the selection list
…a single data point	Select or combo box	Combo box with validator that prohibits custom values	Input field with suggestions and select dialog	Input field with suggestions and value help dialog
…two data points	Select or combo box with two-column layout	Combo box with validator that prohibits custom values	Input field with suggestions and select dialog	Input field with suggestions and value help dialog
...3 or 4 data points with/without an image	Input field with suggestions and select dialog	Input field with suggestions and select dialog	Input field with suggestions and select dialog	Input field with suggestions and value help dialog
…more than 4 data points with/without an image	Input field with suggestions and table select dialog	Input field with suggestions and table select dialog	Input field with suggestions and table select dialog	Input field with suggestions and value help dialog
…several data points and option to narrow selection list down (by defining conditions, selecting ranges)	Input field with suggestions and value help dialog	Input field with suggestions and value help dialog	Input field with suggestions and value help dialog	Input field with suggestions and value help dialog

Selecting Multiple Values or Options

The user can identify an individual value/option based on…	2-12 entries in the selection list	13-200 entries in the selection list	200- 1,000 entries in the selection list	More than 1,000 entries in the selection list
…a single data point	Multi-combo box	Multi-combo box	Multi-input field with suggestions and select dialog	Multi-input field with suggestions and value help dialog
…two data points	Multi-combo box with two-column layout	Multi-combo box with two-column layout	Multi-input field with suggestions and select dialog	Multi-input field with suggestions and value help dialog
…3 or 4 data points with/without an image	Multi-input field with suggestions and select dialog	Multi-input field with suggestions and select dialog	Multi-input field with suggestions and select dialog	Multi-input field with suggestions and value help dialog
…more than 4 data points with/without an image	Multi-input field with suggestions and table select dialog	Multi-input field with suggestions and table select dialog	Multi-input field with suggestions and table select dialog	Multi-input field with suggestions and value help dialog
…several data points and option to narrow selection list down (by defining conditions, selecting ranges)	Multi-input field with suggestions and value help dialog	Multi-input field with suggestions and value help dialog	Multi-input field with suggestions and value help dialog	Multi-input field with suggestions and value help dialog

Resources

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

Elements and Controls

Combo Box (guidelines)
Input Field (guidelines)
Select (guidelines)
Multi-Combo Box (guidelines)
Multi-Input Field (guidelines)
Select Dialog (guidelines)
Table Select Dialog (guidelines)
Value Help Dialog (guidelines)

Implementation

Combo Box (SAPUI5 samples)
Input Field (SAPUI5 samples)
Select (SAPUI5 samples)
Multi-Combo Box (SAPUI5 samples)
Multi Input (SAPUI5 samples)
Select Dialog (SAPUI5 samples)
Table Select Dialog (SAPUI5 samples)
Smart Field with value help dialog (SAPUI5 samples)

Table Toolbar

The table toolbar always appears above the table. The control is used for key actions that impact the entire table.

Usage

Use the table toolbar if:

There are multiple objects on your page and you need to edit only a single table.
You want to show actions as close to their corresponding controls as possible.
You need a title for your table.

Do not use the table toolbar if:

You are using single selection and have only one or two actions. In this case, place the actions on each line.

Responsiveness

To enable responsiveness, use the overflow toolbar control. For more information, see Toolbar Overview – Responsiveness.

Components

The table toolbar can contain several components, including a title and several types of button. Actions are grouped by the following action types:

Finalizing actions, such as Save or Cancel. Finalizing actions are app-specific and are used only if the table is editable.
Business actions, such as Edit or Create. Business actions can be app-specific or general object management actions.
Actions for managing the content, such as Sort or Filter. These settings are also known as “view settings”.
Generic actions, such as Export to Spreadsheet.

Between the groups, add a separator line.

The following content can be part of the table toolbar. Use only the content your users really need. For the remaining content, keep the order shown below:

Title
Variant management or content switch (for example, as used to switch between multiple views in a list report)
Search
Finalizing actions:
- Save
- Cancel
Business actions: Use this action type for app-specific actions. This group contains:
- App-specific business actions
- Actions for object management
  - Create (for new items) or Add (for existing items)
  - Edit
  - Delete (if the object itself is deleted) or Remove (if the reference to an item is removed)
- Paste

The order of actions in this group is not “fixed”. Place all the business actions, except for Paste, in the order of their importance for the use case. Always keep Paste as the last business action in the group.

Try to keep Create/Add, Edit, and Delete/Remove together, but only if this is meaningful in your app.

Actions for content management (view settings)
- Show Details / Hide Details
- Sort
- Filter
- Group
- Column Settings
Generic actions
- Export to Spreadsheet
- Print
Maximize / Minimize
View switch (for example, to switch between table and chart view)
Overflow

All possible components in the correct order

Behavior and Interaction

App-Specific Business Actions

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

Table toolbar with app-specific buttons

Title

A title provides a short, meaningful summary of the content, mostly in a single word. To display a title, use the title control.

In addition, the title can be followed by an item counter (the number of items in parentheses). If no items are currently shown, remove the counter.

Use a title if you need the table toolbar, and if the title of the table is not indicated in the surrounding area. To avoid repeating text, you can use a generic text for the table title, such as Items. Note that the title is truncated if there is not enough space.

Title with item counter in the table toolbar

Variant Management

In tables, a variant stores all the settings that define the table view, such as the column layout, column visibility, sorting, filter settings, and grouping. The variant management control enables users to load, save, and change variants. In most cases, variant management replaces the title.

Variant management in the table toolbar

Title and Variant Management

If you need both a title and variant management, place the variant management control directly after the title. Use a separator between the title and variant management.

Since using both controls often leads to truncation problems, this pattern is not recommended.

Title with variant management

Content Switch

To switch between different predefined views, use a select control or a segmented button. The content switch replaces the title and the variant management control. In the rare case that the content switch is shown together with a title, the content switch follows the title.

A predefined view contains settings for sorting, filtering, grouping, column layout, and column visibility. Nevertheless, in most cases, the content switch is just used for different filter settings like All, Mine, and Others. In this case, make sure that the content switch doesn’t interfere with other filter settings. For example, remove the corresponding filter from the filter bar. If possible, include an item counter per view.

Another common pattern for content switches are views like By X, and By Y, which are usually defined using group settings.

Use the segmented button and the select control as follows:

For a limited set of views (2-3), use the segmented button for desktop and tablet devices. Replace it with a select control if there is not enough screen space.
If the number of views can change or is larger than 3, use the select control.

For more information, see multiple views for list reports.

Segmented button with a counter

Segmented text button to switch content

Select control to switch content

Search

For tables with a large number of items, consider adding a search field. Use a search field only if there is no other way to search within the table (for example, if there is no additional filter bar).

Place the search field on the right side of the toolbar. Since the search field cannot be moved into the overflow menu, always provide a minimum width.

Ideally, search for results in all columns. As a minimum, search in all currently visible columns.

For more information, see Search.

Search in the table toolbar

Edit

There are several options for editing a table:

Edit a Single Item

To allow the user to edit a single item, show an icon-only Edit button at the end of the item (depending on the table control, use sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive; or row actions). The user can click the button to trigger the edit event. Use this event to make the item editable.

Editing a single item

Mass Editing

See: Mass Editing

Edit the Whole Table

To let the user edit a whole table, use a text-only Edit button. When the user triggers the edit action, switch the table to edit mode. In edit mode, do not show the Edit button and add the finalizing actions Save and Cancel instead. Remove any actions that are meaningless in edit mode. Keep the view settings available.

Table in display mode with 'Edit' as the most important action

Table in edit mode

Create / Add

Use a text button for Create or Add actions. If the Create or Add action is a main function, never move it into the overflow.

Table toolbar with 'Create' button

Table toolbar with 'Add' button

Delete / Remove

Use a text button for Delete or Remove actions. In most cases, Delete is used together with Create, while Remove is used together with Add.

If the Delete or Remove action is a main function, never move it into the overflow.

Table toolbar with 'Delete' button

Table toolbar with 'Remove' button

Show Details / Hide Details

Based on the responsive behavior of a table, data can be shown in the pop-in area. With the Hide Details / Show Details segmented button, users can switch between a full data set and a reduced data set.

The tooltip labels are as follows:

Hide: Show less per row
Show: Show more per row

This function is part of the view settings group and is displayed at the first position of this group.

For more information, see Smart Table.

'Show Details' function to show all data in pop-in area

'Hide Details' function to reduce data in the pop-in area

Sort, Filter, Group

When the user chooses one of these actions, open the view settings dialog or the P13n Dialog with only the corresponding settings.

If sorting, filtering, and/or grouping is a common use case in your app, offer one, two, or all three of the corresponding features. Do not provide these features if the table is expected to have only a small number of entries (up to 20 in most cases).
If filtering is a main use case, do not offer filtering on the table toolbar; use the filter bar instead.

Always use only the view settings you really need. For example, do not offer grouping if it does not support your use case.

Ensure a consistent user experience. When a user reopens the app and if variant management is not used, show the table with the same view settings that were last defined by this user.

For more information, see Table Personalization.

Triggers for the different view settings (sort, filter, and group)

Column Settings

Use the table personalization dialog or the P13n Dialog for adding, removing, and rearranging columns.

Offer column settings if you need more columns than those that fit on a tablet screen (which is usually five) to fulfill 80% of your main use cases. Before you do this, try to reduce the number of columns, for example, by using several lines per column or by using the pop-in feature.

Ensure a consistent user experience. When a user reopens the app and if variant management is not used, show the table with the same column settings that were last defined by this user.

For more information, see Table Personalization.

Table toolbar with 'Column Settings' button

Export to Spreadsheet

The Export to Spreadsheet action allows the user to export table rows and is represented by an icon-only menu button.

Table toolbar with the 'Export to Spreadsheet' menu button

Print

The action for printing table items is represented by an icon-only button.

Table toolbar with 'Print' button

Maximize / Minimize

To allow the user to show the table in full screen mode (property: ShowFullScreenButton), show the Maximize button. The user can exit the full screen by clicking the Minimize button.

Table toolbar with 'Maximize/Minimize' button

View Switch

View switches are right-aligned in the toolbar and allow the user to switch between different chart types and different controls for displaying items (for example list, responsive table, grid list). Provide the view switch if a chart relies on subtle color differences or gradients of color. In these cases, users with visual impairments can switch to the table view.

Switches are optional and do not have to be provided if there is no need to switch between different charts or tables.

Define the number of chart types and switches with care. Offer only chart types that are meaningful for visualizing the respective data and that best assist the user. Ideally, offer no more than three types of visualization.

The sequence of chart type switches is not fixed. Sort them in order of importance.

The chart type currently in use is highlighted. To show this, use a segmented button with icons.

For more information about the icons and the chart types they represent, see Chart Toolbar.

Overflow

See: Toolbar Overview – Overflow.

Styles

On the table toolbar, use the following button styles:

If the single primary action for the whole page is on the table toolbar, use the emphasized button style.
if the single primary action for the whole page is not on the table toolbar, you can still highlight the most important button of the table toolbar by using the ghost button style.
For secondary actions and negative path actions, use the transparent button style.
For split buttons and menu buttons, use the transparent button style.
Do not use semantic button styles on the table toolbar.

For more information, see Button and Action Placement.

Guidelines

To indicate if an action can be applied to the current selection:

Enable the action if it always works, regardless of whether or not items are selected.
Enable the action if it can be applied to all selected items.
Enable the action if it can be applied to some of the selected items. If the action is triggered, show a message that informs the user how many items will be affected. Let the user choose whether to apply the action anyway or cancel the action.
Only disable the action if:
- The action can’t be applied to any of the selected items.
- The number of selected items doesn’t match the action. For example, disable Compare if only one item is selected.

For more details, see UI Element States.

Message for an action that applies to a part of a selection

If the items are still available after the action was applied, keep them selected.

For further guidelines, see Toolbar Overview – Guidelines.

Resources

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

Elements and Controls

Action Placement (guidelines)
Action Sheet (guidelines)
Button (guidelines)

Implementation

Overflow Toolbar (SAPUI5 samples)
Action Sheet (SAPUI5 samples)
Toolbar (SAPUI5 samples)
Overflow Toolbar (SAPUI5 API reference)
Action Sheet (SAPUI5 API reference)
Footer Toolbar (SAPUI5 API reference)
Table Personalization Dialog (SAPUI5 API reference)
Toolbar Separator (SAPUI5 API reference)
Toolbar Spacer (SAPUI5 API reference)

Switch

The toggle switch mimics a physical switch. It allows users to set individual features (such as personalization or display settings) to either active or inactive.

Label, optional text, and switch

Usage

Use the switch if:

You want to enable users to set something as active or inactive (for example, within a dialog).
You need to clearly show the mode or state of a setting.
The change takes immediate effect.

Do not use the switch if:

The user has to choose several options or perform extra steps for changes to become effective.
It’s not clear if the control is showing a state or an action. In this case, use a checkbox instead.

Types

There are three switch types: basic, semantic, and with optional text.

Basic Switch (Default)

The basic switch changes something to active or inactive. This is the default switch.

Default switch

Semantic Switch

The semantic switch changes something to ‘positive’ or ‘negative’. An icon is displayed automatically for each semantic state and cannot be changed.

Semantic switch

Switch with Optional Text

You can display a text (sap.m.text or sap.m.objectstatus) next to the switch to indicate what the ‘active’ and ‘inactive’ states mean in your specific use case. Keep the text succinct.

Position the text next to the switch:

Left of the switch in left-to-right writing systems
Right of the switch in right-to-left writing systems

Switch with optional text

Semantic switch with optional text

On/Off Switch

Technically, the switch can also display 2-3 letters within the switch.

This design is obsolete. To avoid localization issues, never use text inside a switch.

Don't

Switch containing text

Behavior and Interaction

The control supports mouse, touch, keyboard and screen reader interaction.

The user can switch between two states: active or inactive. The state is changed by moving the toggle from one side to another or by clicking the empty side. The toggle then moves over.

Styles

Switches can have different states and markups, but are always ‘active’ or ‘inactive’. The control supports an enabled, hovered, and disabled state.

Enabled semantic switch

Hovered semantic switch

Disabled semantic switch

Resources

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

Elements and Controls

Select (guidelines)
Radio Button (guidelines)
Checkbox (guidelines)

Implementation

Switch (SAPUI5 samples)
Switch (SAPUI5 API reference)

Checkbox

A checkbox lets the user set a binary value (such as “true/false”). When the user clicks the checkbox, it toggles between checked and unchecked. Checked means that the state described by the checkbox text applies, or that the item has been chosen.

The checkbox text describes the positive action (as in “true” or “yes”). The text can be either a label control to the left of the checkbox, or a checkbox text that appears to the right of the box.

If there is only one checkbox, you can use a label or text depending on the form format.
If there is more than one checkbox, the label describes the whole group of checkboxes. In this case, use the text property of the checkbox to describe the individual checkboxes.

Within a group of checkboxes, each checkbox can be checked or unchecked. The user can check multiple options.

A checkbox does not apply a setting right away; the changes take effect after user confirmation via a triggering action button (such as Save).

Checkbox enabled/disabled

Usage

Use the checkbox control if:

Only one option can be selected or deselected, for example to accept terms of use. Use it only if the meaning is obvious (single checkbox).
You have a group or a list of options that can be selected independently of each other (checkbox group).
Your use case requires all available options to be displayed right away without any user interaction (also in read-only cases).
The values of the option list are primary information and need to be displayed right away.
Changes to the settings need to be confirmed and reviewed by the user before they are submitted. This helps prevent users from changing settings accidentally.
You want to group multiple suboptions under a parent option, and require an intermediate selection state (tri-state). The tri-state indicates that some (but not all) suboptions are selected.

Do not use the checkbox control if:

The user needs to choose multiple options from a large list. Use a multi-combo box instead.
The user can choose only one option from a list. For a small list, use a radio button group instead. For a large list, use the select control or a list with multi-selection functionality.
You want to offer two options for a “yes/no” or “on/off” type of decision. Consider using a switch control instead.
The user needs to perform instantaneous actions that do not need reviewing or confirming. Consider using the switch control instead.
There is not enough space available on the screen. Use the combo box control instead.