Color Picker

The color picker allows users to choose any color and provides different input options for selecting colors.

Color picker

Usage

Use the color picker if:

Selecting any color freely is the typical use case.

Do not use the color picker if:

Users need to select one color from a predefined set of colors. Use the color palette instead.
Selecting a color from a predefined palette is the typical case, but users should still be able to define their own colors. Use the color palette popover instead.

Responsiveness

The color picker supports cozy and compact content densities.

Size S: Color picker opens in responsive popover

Size M – Cozy form density

Size L – Compact form density

Layout

The color picker consists of the following elements:

The color picker box for setting lightness and saturation
Sliders for setting the hue and transparency (“alpha channel”)
Form elements for:
- Displaying the current and new color settings (Prior to any selection, the default color is white. However, the app developer can set a different predefined color using the setSelected method.)
- Setting the color as a hexadecimal value
- Setting the color as red/green/blue (RGB) value (0 to 255 each) (optional)
- Setting the color as hue/saturation/lightness (HSL) value (hue: 0 to 360 degrees, saturation: 0% to 100%, lightness: 0% to 100%) (optional)
- Switching between RGB and HSL values (if applicable)
- Setting the transparency (“alpha channel”) value of the color (0.00 for full transparency to 1.00 for opaque)

Schematic visualization of the color picker

Types

The color picker comes in 3 flavors:

Simplified: The simplified color picker offers settings for hue, saturation, and lightness, but not for the alpha channel. It shows the current and new color. Text input is only possible for hex values.

'Simplified' color picker

Default: The default color picker allows all settings. It displays input fields either for red / green / blue / alpha or for hue / saturation / lightness / alpha. End users can switch between both sets of input fields.

'Default' color picker

Large: The large color picker allows all settings and displays all fields at the same time.

'Large' color picker

Behavior and Interaction

Mouse/touch: Users select a combination of saturation and lightness in the color picker box (click and drag). Hue and alpha values are selected with sliders.
Keyboard: The tab key is used to set the focus on the sliders and input fields. Values are entered using the corresponding input controls. The sliders react on arrow keys, page up / page down keys, as well as on home and end keys. The color picker box is not keyboard-enabled.

Guidelines

Do not place the color picker directly on a page. Always offer the picker in a popover or dialog.
Use the simplest color picker type that does the job.

Resources

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

Elements and Controls

Color Palette (guidelines)
Color Palette Popover (guidelines)
Color Picker Popover (guidelines)

Implementation

Color Picker (SAPUI5 samples)
Color Picker (SAPUI5 API reference)

Feeds and notes are commonplace in many SAP Fiori applications. The sap.m.FeedInput control allows users to input and post plain text, while the sap.m.FeedListItem control handles and displays this text. Both can be used individually, but they also complement each other well to create a simple feed or notes control.

Usage

Feed Input

Use the feed input if:

A user needs to input small amounts of text without formatting.
You expect multiple instances, such as notes or feed entries.

Do not use the feed input if:

The user needs to format the text (rich text editor).
You need only a single text box instance. In this case, use the text area (for multiple lines) or the text control (for a single line).

Combination of Both Controls (as Feed or Notes Control)

Use both controls if:

You need a feed to show textual posts.
Your users need to input notes.

Do not use both controls if:

You expect extensive social interaction in the feed.
Users need to reply at item level instead of creating a new post.
You want to display SAP Jam feeds.

In these cases, use the social timeline instead (requires SAP Jam).

Responsiveness

Due to their responsive behavior, both controls can be used in small and large view ports or screens.

For better usability, we highly recommend that you do not stretch the controls across the full width on large screens – 2/3 or even 1/2 works just fine. This can easily be achieved using the grid layout .

Feed – Size S

Feed – Size M

Feed – Size L

When the width of the available space falls below 25 rem (for example, in portrait mode on smartphones), the two controls respond as follows:

If a user image previously appeared in the feed input, it will be omitted in narrow screens to give the text field more space.
If there is no user image, there will be no visual change.

Feed input – Responsiveness

In the feed list item, the user’s name, image, and the time stamp move on top of the text. If there is no image, the name and time stamp are left-aligned together with the text.

Feed list item – Responsiveness – With image

Feed list item – Responsiveness – Without image

Layout

Feed Input

The feed input consists of:

A text input field with a placeholder (input prompt)
Example: Add a comment
A Send button
An optional user image

You can also choose not to show user images at all. In this case, the size of the input area increases automatically.

Feed input – Layout – With user image

Feed input – Layout – With generic user image

Feed input – Layout – Without user image

Feed List Item

The feed list item consists of the user’s name and an optional picture of the user who wrote the note or update. The name can contain a link that triggers a quick overview of the user’s profile data. The actual text written by the user follows the name. Below it is a separate byline that can contain a time stamp and an attribute in the form of free text. This allows you to put in your own attribute, such as Approval, Internal, or External. Both the time stamp and the attribute are optional.

If the name is a link, the picture should also be linked with the same attributes.

Feed list item – With user image and linked name

If the user does not have a picture assigned, a placeholder is shown instead:

Feed list item – With generic user image and linked name

The name (and picture) can also be read-only, that is, without a link:

Feed list item – With user image but without links

If the app does not support user images, they can be omitted:

Feed list item – Without user image but with linked name

Here, too, the name can be read-only:

Feed list item – Without user image and read-only name

It’s also possible to display rich text (formatted text) in the feed list item. This feature should be handled with care as it allows for countless custom layouts.

Please see that you use it responsibly and provide your users with a consistent experience. Only deviate from the default layout and font if absolutely required by the use case.

Example use case: Render URLs as links.

Feed list item – Layout – Rich text

Information

The items in the feed list must be homogeneous. This means that they must contain the same layout and visualization. For example, it is not possible to have a feed containing both linked and plain names, or both user images and default images.

Special Case: Multiple Types of Notes

Apps sometimes need to discern between different types of notes. There is an easy way to allow users to choose which type they want to see or add to the list.

You can place a toolbar containing a select control at the top of the feed input control. From there, users can select the type of notes, such as Internal Notes or External Notes. The list of notes must contain only the type selected. If the user adds a note via the feed input, the type must be set automatically according to the selection.

Interaction – Note Types

Components

The feed input and feed list item do not contain subcontrols. However, you can easily combine them to create a simple feed or notes control.

Although the feed input counts as a single control, the input area inherits its behavior from the sap.m.TextArea control.

Behavior and Interaction

Send Message

Initially, the feeder contains a placeholder (input prompt), and the Send button is disabled, with reduced opacity.

Clicking into the input field puts the focus on the field and allows to start typing.

When the user starts to type, the placeholder disappears and the Send button becomes active and more prominent.

If the available width is below 25 rem (for example, in portrait mode on a smartphone), the picture is removed.

To send the text, the user must explicitly click the Send button. Pressing Enter on the keyboard (on-screen or physical) results in a line break.

Feed input – Behavior

Show More Text

When the text exceeds a certain number of characters (you can overwrite the default value), the rest of the text is truncated and a MORE link appears after the truncated section.

The MORE link indicates the possibility of expanding the section of the feed list item itself. Hovering over the link underlines it.

Show Less Text

When the user expands the text, the name of this link changes to LESS, but still behaves the same way as before.

Both texts for the “MORE” / “LESS” links can be modified to suit a particular use case. There is a possibility to use uppercase, lowercase or a mix of them.

Feed and Notes in Tables

In tables, users sometimes need to see if an object has a comment (or feed or note) without further navigation, and even be able to add/edit right from the table.

Add an additional column, named according to the type of user input, such as Comment, Note, or Feed.

Place a link inside each cell with the appropriate action (row: Comment, link: Comment/ row: Feed, link: Post).
If there can be more than one item, add a counter after the text as well (see example on the right).

This solution works with every table control.

Feed and notes in tables (1)

Optional:
Depending on the use case, it might help users if they can see the latest note. The responsive table allows the feed list item (sap.m.FeedListItem) to be used inside a cell.

Reduce the property “maxCharacters” to an amount that your table can handle.
Note that once the maximum number of characters has been reached, a MORE link allows users to expand the text. Technically, this is no problem for the responsive table, but you need to ensure that the layout of your page allows this kind of expansion.

Place a link below the feed list item to allow users to add something (as described above).

Feed and notes in tables (2)

When the user clicks a link, such as Comment or Note, display a dialog showing all comments (notes, feed entries, and so on) along with possible actions, such as Add or Edit, depending on your use case.

There are several ways to show notes (comments, feed entries, and so on) in a dialog:

You can use the feed list item (and feed input) as described in this article.
If only one single note is allowed, you can use the text area.
For a large feed, you can use the timeline control (SAP Jam is required for social features).

Actions On Feed List Items

Applications can define actions that users can perform on individual feed posts. The two most typical actions are Edit and Delete. Other actions can be introduced as required by the use case. To keep the feed as lightweight as possible, don’t overwhelm users with too many actions or complicated actions (max. 5 per post).

Interaction - Actions

Styles

By default, feed entries are separated by divider lines. We recommend that these separators remain enabled, since they help distinguish between individual posts. However, if your list is expected to hold only a handful of entries, you can disable the separators by setting the showSeparators property at list level (not at list item level) to none.

Guidelines

Because the feed list item is built on the basis of the standard list item, it inherits multiple properties that may not make sense in a feed use case.

Use only properties that are described in this article. Especially making the entire feed list item clickable can lead to functional issues and usability problems.

Don’t stretch the feed input or the feed list items across large screens (size L and beyond). This will have a negative effect on usability and readability. Instead, only use 1/3 or even 1/2 of the screen. Implement this with the grid layout .

If you display formatted text (rich text) in the feed list item, use formatting that is beneficial to users, not decorative formatting. Use formatting responsibly, and provide your users with a consistent experience. Deviate from the default layout and font only if absolutely required by the use case (example: render URLs as links).

Resources

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

Elements and Controls

No links.

Implementation

Feed Input (SAPUI5 samples)
Feed List Item (SAPUI5 samples)
Feed (SAPUI5 samples)
Feed Input (SAPUI5 API reference)
Feed List Item (SAPUI5 API reference)

Select

The select control (also known as a dropdown) is commonly used to enable users to select an item from a predefined list.

Usage

Use select if:

Users need to select one item exclusively from a short list of options (for example, fewer than 12 items).
The values of the option list are of secondary importance and do not need to be displayed right away.

Do not use select if:

Users need to choose between two options, such as On or Off and Yes or No. In this case, consider using a switch control instead.
Users need to pick one item from a very large set of options. In this case, consider using the combo box instead.
You need to display more than one attribute. In this case, consider using the input field with a select dialog or a value help dialog instead.
The user needs to search on multiple attributes. In this case, consider using the input field with select dialog or value help dialog instead.
Your use case requires all available options to be displayed right away, without any user interaction. In this case, consider using radio buttons or a radio button group instead.

Information

For more information on which selection control to choose, see the selection control overview.

Responsiveness

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

Size S

Select option list in full screen - Size S

Size M

Select option list – The option list opens above the field if there is not enough space below it - Size M

Size L

Select option list – The option list opens above the field if there is not enough space below it - Size L

Layout

The select control can be placed in toolbars, such as chart toolbars, footer toolbars, or header toolbars, as well as in forms or tables:

Components

Select Trigger

The trigger to open the option list is either the Select field (1), which also displays the current selection, or an icon (3).

Option List

The option list (2) displays all the items available to the user. The selection is always highlighted. Selecting another option from the list moves the highlight to the selected option.

Full Screen Title Bar for Size S

Opening the select control on a smartphone brings up the option list in full screen mode. The full screen mode can be closed using the icon on the top right corner (5).

You need to set a title for the full screen mode (4). We recommend the following format:

Single selection

Select [Entity]

Example: Select Product

Multi-selection

Select [Entities]

Example: Select Products

Anatomy of the select control

Anatomy of the select control - Size S

Behavior and Interaction

Clicking

The Select field always displays the current selection. The user clicks the field to display a list of options to choose from. Once the user selects an option, the list box closes and the selected option is displayed in the field. If there is no Select field but an icon, the user clicks the icon to open the list of options. The currently selected item is always highlighted in the list to help the user identify what has been selected.

Guidelines

Option List

The option list can contain either text-only values (a) or text values with an icon in front (b). Keep the text values as short as possible because the list uses single lines only. Values that are too long may be truncated. This is especially important when you use icons.

Only use icons if they help users better identify or understand the presented options. To set icons, use the icon property for each list entry.

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

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

If your use case requires a blank input field instead of (None), use a combo box instead.

If the select control is placed in a toolbar with an icon as a trigger for sorting, grouping or filtering a set of items, consider the following guideline:

Sort, Group, and Filter:

(Not sorted)
Note: In most cases, this option is not necessary; just show the default sort settings instead.
(Not filtered)
(Not grouped)

For more information about the toolbar, see toolbar overview.

Define a default selection whenever possible (2). If the selected item is not specified, the first one is selected.

(a) Text-only version; (b) icon and text

(1) Selection option list with (None); (2) first value selected

Label

The select control can be displayed with or without a label. If the field is attached to another field, you do not need to define a second label.

Information

Do not provide a blank value to indicate that nothing is selected.

Sorting

The sort option list contains all the items that are available to the user. Choose one of the following styles to order the content:

Logical: Sort items into a meaningful order. Group related options together and show the most common options first, followed by less common options. Sort the options alphabetically if more than eight select options are available. This helps the user find the right option quickly.

Example of logical sorting

Alphabetical: Sort currencies, names, and similar content alphabetically.

Example of alphabetical sorting

Numeric: Sort numeric values into a sequential order, with the lowest number first.

Example of numeric sorting

Chronological: Sort time-related information into chronological order, with the most recent first.

Example of chronological sorting

Width

The select control is usually used in forms, where the width is determined by the form element or container in which the select control is embedded.

If you need to restrict the width to a defined value, you can set the width accordingly. However, we do not recommend defining a fixed width. Where possible, use layout containers (such as a form, simple form, or responsive grid layout), and define the width via the layout data property.

Do not allow the control to auto-adjust based on the selection.

Information

If the text length is fixed and doesn’t require localization (for example, currency codes), consider reducing the width.

Width of the Option List

By default, the width of the option list adapts to the width of the longest entry. The maximum width of the option list is set to 600 px.

Maximum width of the option list

Text Wrap in the Option List

The option list doesn’t support horizontal scrolling. By default, entries that exceed the maximum width of 600 px for the dropdown are truncated. If you expect the dropdown to contain longer entries, we recommend wrapping items in the option list to enable users to read the full text, (property: wrapItemsText). If wrapping is enabled, the text can wrap to multiple lines.

Option list with wrapped text

Unit of Measurement

You can use the layout options of the form to can add the unit of measurement (UoM) after select. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

Developer Hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

Semantic Colors

Different value states or meanings can be indicated by using semantic colors. The visual states are shown below in their regular state (left) and focused (right). Note that the positive/success state does not show a message on focus.

For more details on the correct usage, see How To Use Semantic Colors.

Neutral

Neutral (focus)

Information

Information (focus)

Success

Success (focus)

Error

Error (focus)

Warning

Warning (focus)

Value State Text

The select control can display the value state text even if the dropdown is open. This ensures that the value states are shown in all situations and on all devices. When the user opens the dropdown, the value state sticks to the top and does not scroll away. The control also supports multi-line text for the value state.

Value state text displayed when the dropdown is open

Read-Only

The select control can be displayed as read-only (property: editable, default = “true”). If the editable property is set to “false”, interaction with the control is disabled. The control remains focusable, but the background and border are changed to indicate that it is read-only.

Select read-only

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)
Multi-Combo Box (guidelines)
Input Field (guidelines)
Form (guidelines)
Radio Button (guidelines)
Checkbox (guidelines)
Toolbar (guidelines)
How To Use Semantic Colors (guidelines)

Implementation

Select (SAPUI5 samples)
Select (SAPUI5 API reference)

Rating Indicator

The rating indicator can be used to rate content or to indicate a rating. It enables users to rate an item on a numeric scale. The most popular scale is 1 (lowest) to 5 (highest).

Rating indicator

Responsiveness

The rating indicator runs on all form factors and therefore works on all devices. It is embedded in a container and thus behaves as part of it.

Rating indicator as part of a form – Size S

Rating indicator as part of a form – Size M

Layout

Context

You can use the rating indicator in forms, tables, in a dialog box, or in the filter bar.

Rating indicator as part of a form

Rating indicator in the filter bar / as part of a table

Rating indicator as part of a dialog

Popover with Details

In collaborative rating scenarios, the rating indicator shows an average of all ratings. You may show the sum of ratings in brackets behind the rating indicator as a text or link. You may also add a popover that shows the detailed ratings for the average of all ratings.

Rating details in a popover

Behavior and Interaction

Hover

When the user hovers over the rating indicator, a different icon or image is shown (property: iconHovered). This is an orange star by default.

Select

If enabled for rating, the rating that the user previously selected is shown. When the user performs a rating, an event is triggered.

Types

There are two types of rating indicators:

Interactive – used for rating an item
Disabled

As the non-interactive state (rating result preview) is not available currently, use the disabled state instead.

Interactive state

Non-interactive state

Display mode

Disabled

Properties

Rating Symbols

You can also specify the URLs for the images or icons that are used as rating symbols (property: iconUnselected). Five star symbols are used by default. Although you can use other images or icons, we generally recommend that you use the star symbol. You can only choose 1 symbol for the unselected and 1 for the hovered state.

Number of Rating Symbols

You can specify the number of rating symbols (property: maxValue). We recommend using a maximum of 7 symbols, although 5 symbols are preferred.

Float Values

Float values can be visualized as a half or full star (property: visualMode). The rating indicator can display a half star only in preview mode (disabled).

Size of Rating Symbols

The recommended sizes of the image or icon to be displayed are:

Large: 2 rem (32 px)
Normal: 1.375 rem (22 px) – default
Small: 1 rem (16 px)
XS: 0.75rem (12px)

Possible sizes of a rating indicator: L, M, S, and XS

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

Form (guidelines)
Table (guidelines)
Dialog (guidelines)

Implementation

Rating Indicator (SAPUI5 samples)
Rating Indicator (SAPUI5 API reference)

Table Personalization Dialog

The table personalization dialog allows you to display and modify table settings. It is a UI pattern that defines the column order and visibility.

Usage

Use the table personalization dialog if:

You have small tables.
You have a manageable number of columns.

Do not use the table personalization dialog if:

You have large tables.
You have a lot of columns to manage.

For larger tables you can use the P13n dialog (sap.m.P13nDialog) instead.

Responsiveness

On a desktop and tablet, the control appears as a dialog window.

On smartphone devices, always display the table personalization dialog in full screen mode.

Table personalization dialog - Smartphone - Size S

Table personalization dialog - Tablet - Size M

Table personalization dialog - Desktop - Size L/XL

Layout

Position on the Screen

The dialog always opens in a modal window in the center of the screen.

For smartphones, stretch the dialog to fill the entire screen. For tablet and desktop devices, keep the modal window.

Layout of the Dialog

The table personalization dialog comprises the following five areas:

(1) Header

(2) Toolbar

(3) Subtoolbar

(4) Column list

(5) Footer toolbar

Table personalization dialog – Overview

Components

The table personalization dialog contains the following sections:

Header

The header displays the dialog title and the Reset button to revert to the initial state.

Table personalization dialog – Header

Toolbar

The toolbar displays the Move Column Up and Move Column Down buttons and the Search field.

Table personalization dialog – Toolbar

Subtoolbar

The subtoolbar displays the Select All checkbox for selecting all columns.

Table personalization dialog – Subtoolbar

Column list

The column list displays the available columns. The user can filter the selection using the search field in the toolbar.

Table personalization dialog – Column list

Footer toolbar

The footer toolbar displays an OK and a Cancel button.

Table personalization dialog – Footer toolbar

Behavior and Interaction

Open the Dialog

To open the table personalization dialog, the user clicks the (Settings) button on the right-hand side of the table toolbar.

Table personalization dialog – Table

Table personalization dialog – Open dialog

Show or Hide Columns

To show or hide columns, the user selects or deselects the checkbox for a column (list item).

(1) Columns are visible in the table.

(2) Columns are hidden in the table.

Table personalization dialog – Show/Hide

The user can also show or hide all columns with just one click. A checkbox on the left-hand side of the subtoolbar enables all list items to be selected or deselected.

(1) Columns are visible in the table.

(2) Columns are hidden in the table.

Table personalization dialog – Show all

Table personalization dialog – Hide all

Move Columns

Users can change the order of the columns in the table using the (Move Column Up) and (Move Column Down) buttons in the toolbar.

Table personalization dialog – Move buttons

Move Column Up

(1) Select a column (by clicking on the list item).

(2) Use the Move Column Up button to move the column to the left in the table.

Note: The Move Column Up button is disabled for the first item in the list.

Table personalization dialog – Select

Table personalization dialog – Move Column Up

Move Column Down

(1) Select a column (by clicking on the list item).

(2) Use the Move Column Down button to move the column to the right in the table.

The Move Column Down button is disabled for the last item in the list.

Table personalization dialog – Select

Table personalization dialog – Move Column Down

Search/Filter Columns

Users can search for or filter columns using the search field in the toolbar.

Table personalization dialog – Search field

The search is a live search (also known as “search-as-you-type”), which is triggered by each character the user enters or deletes. For more information, see search.

Table personalization dialog – Search column

To clear the filters, the user can delete all characters manually, or use the icon.

The list then shows all columns again.

Table personalization dialog – Search reset

Reset Personalization

The Reset button in the dialog header resets all settings to the initial state.

If the table personalization dialog is used together with variant management, the button resets the changes to the initial state of the selected variant.

Table personalization dialog – Undo

Confirm/Cancel Changes

The changes are applied when the user closes the dialog with the OK button.

The Cancel button closes the dialog without applying the changes.

Table personalization dialog – OK/Cancel

Resources

Elements and Controls

Toolbar (guidelines)
Button (guidelines)
Search (guidelines)
List (guidelines)
Footer Toolbar (guidelines)

Implementation

Table Personalization Dialog (SAPUI5 samples)
Table Personalization Controller (SAPUI5 samples)
Table Personalization Dialog (SAPUI5 API reference)
Table Personalization Controller (SAPUI5 API reference)

Slider

A slider is a control that enables the user to adjust single values within a specified numerical range.

Slider example

Usage

Use the slider to change values with graphical support.

Responsiveness

The slider itself is not responsive. It adjusts to the responsiveness of its parent container by recalculating and resizing the width of the control.

The slider supports the cozy and compact form factors. The compact form factor is used for apps that run on devices operated by a mouse and keyboard.

Types

Only a horizontal slider is available.

Behavior and Interaction

Changing the Value

If the slider is editable, the hand cursor appears when the user hovers over the grip.

The user can change the slider setting in two ways:

By using drag and drop to adjust the grip
By clicking the bar. The grip then moves to this new position.

The grip can be moved with or without increments based on the predefined steps.

Changing the value

Slider with Text Fields

The slider can be used with text fields instead of tooltips. In this case, the value of the grip is displayed.

Slider with text field

Slider with Input Fields

The slider can be used with input fields instead of text fields. This allows the user to enter a specific value.

Slider with input field

Slider with Tick Marks

You can apply tick marks to the slider. The tick marks are related to the step property, and are responsive. If the distance between 2 tick marks is less than 8 px, all tick marks except for the first and last disappear.

Slider with tick marks

Slider with Tick Marks and Labels

If tick marks are set, you can define labels for the tick marks. The labels are displayed below the tick marks and show the corresponding value of the tick mark. The labels must always be numbers, and must never overlap. You can also define labels only for specific tick marks if you don’t need a label for every tick mark on the slider. The application developer is responsible for defining a reasonable set of tick marks.

If there is not enough horizontal space to display all the labels, a responsive mechanism is activated. The first and the last label are always visible.

Slider with tick marks and labels

Custom Values

You can define custom values as labels. This can be useful if your scenario requires descriptive intervals, such as as dates. Always keep the values as short and meaningful as possible.

Slider with custom values as labels

Developer Hint

In order to use custom scales in a slider, you must map them to the floats for the slider scale.

Styles

The slider can be shown with or without a progress bar. By default, the progress bar is shown.

Examples

Slider without progress bar

Slider with progress bar

Properties

The step property must be positive. If a negative number is provided, the default value 1 is used instead.
The minimum, maximum, and value properties can be decimals (float values). The slider automatically sets the minimum value to 0 and maximum value to 100 by default.
The width of the control can be provided in %, em, px, and all possible CSS units. The slider automatically sets the width of the slider to 100% by default.

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

Text (guidelines)
Input Field (guidelines)

Implementation

Slider (SAPUI5 samples)
Slider (SAPUI5 API reference)

Range Slider

A range slider is a user interface control that enables the user to select a value range within a predefined numerical interval.

Range slider

Usage

Use the range slider if you want to select a value range within a predefined numerical interval. If you want to specify only a single value within a predefined numerical interval, use the slider instead.

Responsiveness

The range slider itself is not responsive. It adjusts to the responsiveness of its parent container by recalculating and resizing the width of the control. The range slider supports the cozy and compact form factors.

Types

Only a horizontal range slider is available.

Components

The range slider consists of:

Progress line
Minimum and maximum value
Grips
Tooltips or input fields

Range slider components

Behavior and Interaction

Changing Values

If the range slider is editable, the hand cursor appears when hovering over the range slider with the mouse. A tooltip also appears when hovering, displaying the current values of each grip. The grips move together with the corresponding tooltips.

The user can change the value range on the slider in two ways:

By using drag and drop to adjust the grips
By clicking the bar outside the value range. The corresponding grip then moves to the new position.

The grips can be moved with or without increments based on the predefined steps.

Range slider on hover

Range Slider with Input Fields

The range slider can be used with input fields instead of tooltips.

Range slider with input fields

Moving the Entire Range

Users can move the entire value range by dragging and dropping the progress line.

Range slider - Moving the entire range

Equal Values

The grips of the range slider can be positioned on the same value.

Range slider with equal values

Overlapping

The grips of the range slider can be moved across each other. The minimum can become the maximum, and vice versa.

Tick Marks

You can apply tick marks to the range slider. The tick marks are related to the step property. For example, if you have a range from 1 to 100 and a step of 10, the range slider will have 11 tick marks. The tick marks are responsive. If the distance between 2 tick marks is less than 8 px, all tick marks except for the first and last disappear.

Range slider with tick marks

Tick Marks and Labels

If tick marks are set, you can define labels for the tick marks. The labels are displayed below the tick marks and show the corresponding value of the tick mark. The labels must never overlap. You can also define labels only for specific tick marks if you don’t need a label for every tick mark on the slider. The application developer is responsible for defining a reasonable set of tick marks.

If there is not enough horizontal space to display all the labels, a responsive mechanism is activated. The first and the last label are always visible.

Range slider with tick marks and labels

Custom Values

You can define custom values as labels. This can be useful if your scenario requires descriptive intervals, such as as dates. Always keep the values as short and meaningful as possible.

Range slider with custom values as labels

Developer Hint

In order to use custom scales in a slider, you must map them to the floats for the slider scale.

Properties

The step property must be positive. If a negative number is provided, the default value 1 is used instead.
The minimum, maximum, and value properties can be decimals (float values). The slider automatically sets the minimum value to 0 and the maximum value to 100 by default.
The width of the control can be provided in percentage (%), em, px, and all possible CSS units. The slider automatically sets the width of the slider to 100% by default.
The range property determines the range in which the user can select values. If the value is lower/higher than the allowed minimum/maximum, a warning message is displayed.
The inputsAsTooltips property indicates whether input fields are being used as tooltips for the grips.

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

Slider (guidelines)
Input Field (guidelines)

Implementation

Range Slider (SAPUI5 samples)
Range Slider (SAPUI5 API reference)

Date Picker

The date picker lets users select a localized date using touch, mouse, or keyboard input. It consists of two parts: the date input field and the date picker.

Use this control if the user needs to enter a single date or a date range. The control also allows users to navigate directly from one month or year to another.

Usage

Use the date picker if:

You need a range and know that your user is a power user who has to input lots of data. If the keyboard is the primary device used for navigating the app, use two input fields. This allows the user to quickly jump from field to field. By selecting a date in one of the fields, the other field should know what is selected and jump to the same selection.

Responsiveness

The date picker provides responsive behavior that allows for simple operation on all devices. It is smaller in compact mode and provides a touch-friendly size in cozy mode.

Clicking the date picker button opens the popover in full screen. To close it, the user can select a date (which triggers the close event), or click Cancel without selecting a date. Clicking the date input field allows the user to type and does not open the date picker popover.

Date picker on a smartphone

Date picker on a desktop device

Components

The date picker has two components: the date input field (1) and the date picker button (2). On all devices users can either use the input field to type a date or use the date picker button to open the date picker calendar.

Date picker with input field and button

Date Input Field

In the input field, the user can enter a date directly or select it using the date picker. The system validates the entry and provides the user with feedback. You can also show placeholder text in the field.

Date Picker

With the date picker, the user can see a day view, month view, year view, or year ranges.

The current day (1) and the selected date (2) are highlighted. The calendar week is also visible in the day view. The calendar closes when a final day is selected. The user can click the arrows to navigate to the previous and the next day (3), month (4), or year view (5), depending on the current view. To select a date the use can use the calendar (6).

The selected date is shown with a blue background. The current day is indicated with a purple border and owns the focus.

The date picker can also show special days, which are highlighted with a colored line at the bottom of the date cell. For more information about the colors and legend, see Legend for Highlighted Days.

Date picker with a selected date and the current date

Clickable areas of the date picker

Date picker with highlighted days

You can change the default focus “today” to another date. This can save users several clicks when they create events. For an event end date, for example, the focus should propose a date in the future (after the start date).

Use case-specific focus date

Month and Year Views

The month and year views can be used separately in a month or year picker. The year ranges are related to the year view and are not used separately. Selecting a year range navigates back to the year view, not the day view.

Month view in the date picker

Year view in the date picker

Year ranges in the date picker

Footer

You can add a footer with OK and Cancel buttons to the date picker popover. However, we advise against this unless it’s very important that the user can pick multiple values (day, month, year) without closing the popover.

The default and recommended behavior is to close the date picker popover upon selection of the day (or month/year for the month and year pickers).

Date picker with footer

Behavior and Interaction

Selecting a Date

The user selects a date by clicking the date. After the user selects a day, the calendar closes and the date appears in the date input field.

Date selection

Clicking the arrow shows the next day, month, or year view.

Navigating to the next month

If the current month is clicked, the view changes to the month view and the user can change the month.

Switching to month view

By clicking on a month, the user changes the month and the view changes to the day view.

Selecting another month

The user can similarly change the year. By clicking the current year, the view changes to the year view. After the user selects a year, the view changes back to the day view.

Switching to year view

After the user selects a year, the view changes back to the day view. The date in the date input field stays the same until the user selects a new date.

Selecting another year

Styles

Value States

The date picker supports the following value states:

Regular
Positive
Warning
Error
Information

You can display a value state text for error, warning, and information states to provide hints for the user.

For more information on how to use the different semantic states, see How to Use Semantic Colors.

For more information about different value states, see UI Element States.

Date picker value states

Guidelines

Date Formats

Long Date Format

Use the long date format for master list/object list item/title and object header/title. Here are some examples:

English (US): January 16, 2022
German (DE): 16. Januar 2022
Danish (DK): 16. Jan. 2022

Short Date Format

Use the short date format for master list/object list item/list of object attributes if space is a concern. For example, you might need to save space if there is a label with the date. Here are some examples of the short date format:

English (US): 1/16/22
German (DE): 16.01.22
Japanese (JP): 22/01/16

Relative and Medium Date Format

If appropriate, use a relative format for master list/object list item/list of object status. For example: today, 1 day ago, 2 days ago, and so on up to 6 days ago. After 6 days, use an absolute date with the medium format.

Use the absolute date with medium format in the corresponding object header in the details area. Do not use the relative format here.

Responsive Table

If screen space is at a premium (for example, if there are too many columns), use the short date format in table cells. Otherwise use the medium format.

If you need to display the weekday, use the full format. For example:

English (US): Sunday, January 16, 2022
German (DE): Sonntag, 16. Januar 2022
French (FR): dimanche 16 janvier 2022

Resources

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

Elements and Controls

Responsive Table (guidelines)
Date Range Selection (guidelines)
Time Picker (guidelines)
Date/Time Picker (guidelines)

Implementation

Date Picker (SAPUI5 samples)
Date Picker (SAPUI5 API reference)

Time Picker

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

Usage

Use the time picker if:

You want the user to select a time.
You want the user to select a time range. In this case, one time picker can be used to set the starting time and a second one to set the end time.
You want the user to select a detailed duration, such as 1 minute and 30 seconds.

Do not use the time picker if:

You want the user to select a duration such as 15 minutes, 30 minutes, 1 hour, or 2 hours. In this case, use the select control instead.

Responsiveness

The time picker comes with a cozy mode and a compact mode. In the compact mode, the time input field and the button are smaller than in the cozy mode. In the compact mode, there are also arrows that the user can click to set hours, minutes, and so on. For more information, see the article on content density.

On desktop (size L/XL) and tablet (size M) devices, the user can enter a time in the input field of the time picker, or set a time via the time picker dropdown which opens when the user clicks the time picker button.

For mobile (size S) devices, the tap area is the same as for a tablet, and the user can type a time in the time input field. Unlike on a tablet or desktop, the time picker dropdown does not open below the time input field, but rather in a subview.

Cozy and compact mode of the time picker

Components

The time picker consists of a time input field (1) and a time picker button (2). On desktop, tablet, and mobile devices, both elements have their own click area. Clicking the time picker button opens the time picker dropdown.

You can set a predefined time, which shows as the initial value in the time input field and the time picker dropdown. Users can overwrite the initial value manually at any time.

Time picker input

Time Input Field

The time input field allows the user to enter a time directly in the field, or select it using the time picker dropdown. The input is validated and feedback is given to the user.

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

Time Picker Button

When the user clicks the time picker button, the time picker dropdown opens to allow the user to choose a time.

Time Picker Dropdown

In the time picker dropdown, the user can select a time by setting hours, minutes, seconds and AM/PM or a subset of these (with hours and minutes only).

Dropdown with hours and minutes

Dropdown with hours, minutes, seconds, and AM/PM

Behaviour and Interaction

Selecting a Time (Desktop Device)

The user clicks the time picker button, which opens the time picker dropdown. In the time picker dropdown, the user can set the time either with the mouse or by using the keyboard arrows. The Page Up and Page Down keys can also be used to set the current selection to the lowest or highest value, and the Home and End keys can be used to go to the first or last element of the picker.

When the desired time has been selected, the user can confirm this selection by clicking the OK button. If the user wants to close the dropdown without changing the time to the selected time, this can be done by clicking the Cancel button or by clicking outside the dropdown.

Preventing Errors

The user can also select a time by clicking the time picker input field and typing the desired time in the field. You can prevent users from making incorrect entries by not allowing them to type in certain characters (see mask input). If the user enters a time that has the correct format but is invalid (such as 12:60:85), the time picker displays a validation error.

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

Time picker dropdown and input field

Selecting a Time (Tablet or Mobile Device)

On tablets and mobile devices, users can select the time by tapping the time picker button. The timer picker dropdown opens beneath the input field (a subview is opened on mobile devices). The user sets the hour by touching the hour element and then swiping up or down. To set the minutes, seconds, and AM/PM, the user also touches the corresponding element and swipes up or down to set the right value.

To confirm the selected time, the user taps the OK button. Tapping the Cancel button cancels the selection. On tablets, the selection can also be cancelled by tapping outside the time picker dropdown.

Set the time by swiping up and down (mobile)

Style

The Time Picker has five basic value states:

Regular
Information
Success
Warning
Error

The information, warning, and error states can also have a message with additional information below.

Time picker value states

Guidelines

Time Formats

Seconds

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

Time Zone

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

12-Hour System

In the 12-hour system, the date picker can contain selections for hours, minutes, seconds, and AM/PM.

24-Hour System

In the 24-hour system, the date picker can contain selections for hours, minutes, and seconds. AM/PM is not available in this mode.

For more information, see formatting time.

Properties

AM and PM are locale-dependent. Therefore, the locale can be set using the property “localeId”.

You can set the display format (property: displayFormat) to define the format in which the time input field and the time picker dropdown display the time. For more information about time formats, see the article on formatting dates.

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

Date Picker (guidelines)
Date/Time Picker (guidelines)
Input Field (guidelines)
Select (guidelines)
Formatting Time (guidelines)
Formatting Dates (guidelines)
How To Use Semantic Colors (guidelines)

Implementation

Time Picker (SAPUI5 samples)
Time Picker (SAPUI5 API reference)

Combo Box

The combo box control allows users to select an item from a predefined list.

The control provides an editable input field for filtering the list, and a dropdown menu with a list of the available options.

If the entries are not validated by the application, users can also enter custom values.

Usage

Use the combo box if:

Users need to select a single item from a long list of items (minimum 13, maximum 200 entries).
The values of the option list are secondary information and do not need to be displayed right away.

Do not use the combo box if:

Users need to select from a list of two options, where one of the options can be implied as on and off or yes and no. Consider using a switch control instead.
Users need to pick one item from a small set of options with up to 12 entries. Consider using the select control instead.
Users need to pick one item from a large set of options with more than 200 entries. Consider using the input field control with a select dialog or value help dialog instead.
You need to display more than one attribute. Consider using the input field with select dialog or value help dialog.
Searching on multiple attributes is required. Consider using the input field with select dialog or value help dialog.
Your use cases require that all available options should be displayed right away without any user interaction. Consider using radio buttons or a radio button group.

Information

For more information on which selection control to choose, see the selection control overview.

Responsiveness

Size S

Size M

Size L

Also see the section on mobile handling below.

Components

Title

A descriptive heading (1).

Input Field

The input field (2) displays the selected value. Users can type any character to filter the option list.

Dropdown Arrow

The dropdown menu’s arrow (3) collapses and expands the option list.

Option List

The option list (4) contains a list of values (5) that users can choose from.

Size S

Size M/L

Two-Column Layout

Use the combo box with a two-column layout if you need to display additional information for the selection options, such as currencies, country abbreviations, or system abbreviations.

Users can filter both columns simultaneously showing only matching entries.

Combo box with two-column layout

Grouping

You can group the items in the suggestion list by a specific attribute and separate them visually with a group header.

The group headers are not interactive.

Grouped suggestion list

Grouped suggestion list - Size S

Behavior and Interaction

Select a Value

There are three ways to select an item from the list:

Select the item directly from the dropdown list.
Type the item into the input field.
Use the up and down arrows to navigate the list.

Clicking the input field places the cursor in the field (1). Clicking the arrow opens the option list (2). When the user starts typing, the list is filtered accordingly. The first item that starts with the characters entered is highlighted in the list and autocompleted in the input field (3). Up/down moves the highlight in the list and populates the value in the field (4). Selecting a value closes the list of options (5).

Developer Hint

With the showitems API, you can open the option list without having the dropdown arrow in a “pressed” state. Clicking the arrow again opens the full option list and changes the state to “pressed”. This allows you to show some items on focus and all items on click.

Autocomplete

When the first few letters are typed in the input field, the control performs autocomplete to help users to easily select one item from the option list.

Warning

The typeahead input feature is not available on Android devices.

Choose from Option List

The option list displays all the available items the user can choose from. The selection is always highlighted. Selecting another option from the list moves the highlight to the newly selected option.

Clicking the arrow opens the option list below the field. If there is not enough space, the list is displayed above the input field.

Selecting a value

Filtering the Option List

When the user starts typing in the input field, the option list is filtered. Only items that match the characters entered are shown in the dropdown list. The default filtering method is “starts with per term”, which matches the beginning of each word in an item’s text.

In addition, application developers can set a custom filtering method “starts with” or “contains” (method: setFilterFunction). The “starts with” approach filters only for items where the beginning of the label matches the query entered. The “Contains” approach searches the full label for a match.

As a visual hint for the user, the matched characters are highlighted in the option list items. The highlighting works on the basis of “starts with per term”, regardless of the filtering method.

If the filtered option list contains items that start with the characters entered by the user, the first matching, unselected item is autocompleted in the input field.

Combo box - Default filtering and autocomplete

Combo box - Default filtering in both columns and autocomplete

Auto-Resize

The width of the option list adapts to its content. The minimum width is the input field plus the dropdown arrow. The maximum width is the part of the screen furthest to the right. If the option list content requires even more width, entries become truncated.

Option list – Minimum width

Option list adapts to long entries

Mobile Handling

The user can enter text into the input field (supported by autocompletion). Clicking the dropdown arrow of the combo box (1) opens in a full-screen dialog (2). The user can now modify the selected entry by clicking the input field of the combo box. The mobile keyboard is then displayed, and the user can begin to enter a new term to filter the option list, also supported by autocompletion (3). The option list closes when the user clicks the OK button at the bottom of the list (4) or selects an item in the list (5).

Information

For information on how to manage leading and trailing white space (blanks) when copying and pasting text into input controls, please see removing leading and trailing white space.

Styles

A combo box has different styles for its different states. Here are some examples:

Unselected

Unselected with predefined placeholder

Unselected on hover

Arrow on hover

Focus

Expanded

Autocomplete

Error

Warning

Success

Information

Warning message with long, wrapping text

For more information on how to use the different semantic states of the control, see How to Use Semantic Colors.

Guidelines

Label

The combo box control can be displayed with or without a label. If the field is attached to another field, you do not need to define a second label. For more information, see the article on how to use labels in SAP Fiori.

Placeholder

Do not use the placeholder attribute as an alternative to a label. This is important because the placeholder text is overwritten as soon as the form is filled out. Labels are necessary to indicate the meaning of the form fields when the placeholders are no longer visible. Show a placeholder only if the user needs a hint on data entry. Do not repeat the content of the label. A hint could be a sample value or a brief description of the expected format. Read more about how to use placeholders.

Option List

The option list contains text values only. Keep the text values short because the list is represented using only single lines. Values that are too long might be truncated.

If you need to express that none of the selection options are selected, show a blank input field. Define a default selection whenever possible.

Sorting

We recommend sorting options alphabetically to help users find the right option quickly. For more sorting rules, check out the guidelines for the select control.

Width

You can adjust the width of the option list to some extent.

The combo box control is usually used in forms, where the width is determined by the form element or container in which the combo box control is embedded. Therefore, we do not recommend defining a fixed width, but rather working with proper layout containers that have a defined width, such as the following properties: “form”, “simpleform”, “responsivegridlayout”, and “layoutdata” .

If you need to restrict the width to a defined value, set the width accordingly.

Keep in mind that there is no horizontal scrolling in the option list. Entries in the list that are too long become truncated and users may not be able to read them.

If localized text is not an issue, consider using a smaller width.

Unit of Measurement

You can use the layout options of the form to add the unit of measurement (UoM) after the combo box control. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

Developer Hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

Properties

Selection

When you select a value, there are two events:

Change: Occurs when the text in the input field is changed and the focus leaves the input field or the user presses the Enter key.
Selection change: Occurs when the user types something that matches an item in the list; also when the user clicks a list box item, or when navigating via keyboard.

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)
Multi-Combo Box (guidelines)
Input Field (guidelines)
Form (guidelines)
Radio Button (guidelines)
Checkbox (guidelines)
Switch (guidelines)

Implementation

Combo Box (SAPUI5 samples)
Combo Box (SAPUI5 API reference)

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.

4. Navigation

The navigation area contains back and forward arrows, the Today button, a date interval link, and the time strip. Clicking the Today button takes the user to the period containing the current day. Clicking the date opens a date picker for direct navigation.

5. Time strip for hours/days/months

The time strip reflects the selected view, and shows the hours, days or months that are currently visible. In all views that show days (Days, 1 Week, 1 Month), you can display calendar weeks in an additional line below the time strip (property: showWeekNumbers).

6. Row header

The row header identifies the object for which the appointments are shown. It pops in if there is not enough space. The row header can contain a picture or icon, a title, and a subtitle.

You can also add an action on the row header (event: rowHeaderClick).

7. Row

The row contains all appointments for an object. You can turn the alternating row coloring on or off. By default, the alternating rows option is turned on.

8. List item

The list item contains the row header, row, appointments, and interval appointments. Each row can show different working and non-working days.

If the users have a specific working schedule, the non-working days can be different on each row. This can be applied not only for weekends, but also for non-working days based on specific schedule differences.

9. Interval appointment

Each row can also have interval appointments, which differ from half-sized appointments visually and in that they are always at the top of the row. Interval appointments can be used to show appointments that last for a longer period of time, such as vacations or workshops.

You can opt to hide the space reserved for interval appointments if no such appointments exist for that time period.

10. Appointment

Appointments consist of an icon or picture, a title, and a subtitle. Concurrent appointments are shown one above the other.

There are four types of appointments:

Regular: Displayed in two rows. One-row display is also possible if the appointmentsReducedHeight property is set to “true”.
Half-size: Always displayed in one row, shows the title.
Large: Always displayed in three rows, also shows the description for each appointment (if available).
Automatic: The number of rows is determined automatically.

Appointment Info Rows

Title only 1 row

Title + text
or:
Title + description 2 rows

Title + text + description 3 rows

You can define the colors for different appointment types. Appointments can also be set to tentative.

The control can register a click event on the appointment, but the app development team must define what happens next.

In the Months view, appointments within the same calendar week are combined to save space. The combined appointment shows the number of appointments in the same week. If an appointment takes place between two calendar weeks (for example, from Sunday to Monday), it is not included in the combined appointments for either calendar week.

A list of the appointments in a combined appointment can be shown in a popover. However, this must be implemented by the app team. The control only provides the click event.

If necessary, you can disable combined appointments (property: GroupAppointmentsMode, value: “Expanded”).

Users can copy and paste appointments to a new position in the planning calendar using keyboard combinations (Ctrl/Cmd + drag and drop to the new position).

Planning Calendar Legend

To show the types for days and appointments, the planning calendar uses a specific legend control
(sap.m.PlanningCalendarLegend).

Users open the planning calendar legend using a standard legend button in the toolbar (). Like all other actions in the toolbar, the app developer must add the legend button explicitly.

The app team also needs to decide which container to use for the planning calendar legend. We recommend placing the legend in a popover to keep the context. You can also use a dialog, or, if there is sufficient screen real estate, show the legend as dynamic side content.

The planning calendar legend has two non-collapsible sections containing legend elements. By default, these are called Calendar and Appointments. The app developer can configure the section names using the itemsHeader and appointmentItemsHeader properties. If no elements are available for a section, it is not displayed.

The Calendar section contains standard legend items: Today, Working Day, Non-Working Day, and Selected (only in the 1-month view on mobile). The app team must ensure that the Selected element is added to the planning calendar legend when the planning calendar is viewed in 1-month mode in a smartphone size. This is not provided by the control. If any of the standard legend items are not needed, you can switch them off (property: standardItems).

You can also apply colors for special days in the Calendar section. The planning calendar legend does not automatically use the colors defined for special days in the planning calendar – this must be done by the app team.

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.

A multi-select toggle can also be provided in the toolbar. This can be used, for example, to select multiple people in order to delete them from the planning calendar.

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

Depending on the current visible interval, appointments might be smaller and the text cut off. The user can click the appointment to see the details.

View switch

The user can change the calendar view with the select control (dropdown). For example, to get an overview of a whole year, the user selects the Months view. Which view is most useful depends on the average length of appointments and the use case.

Today

The user can trigger this action to go back to the current date/moment.

Back and forward navigation

The arrows allow the user to navigate to the next or previous interval.

Date picker

The user can open a date picker to select the start time for the visible interval. What is shown initially in the picker differs depending on the view.

Snapping Header

The header area of the planning calendar can remain fixed on top of the screen (property: stickyHeader), which allows users to view calendars with a lot of rows without losing the context.

Header snaps to top when scrolling down

Drag and Drop

Drag and drop can be used to move appointments (to enable Drag and Drop use property: enableAppointmentDragAndDrop). Moving an appointment automatically changes its start and end times (for example, if an appointment is scheduled from 1:00-2:00 PM, the user can drag it and change the time from 2:00-3:00 PM) . When dragged, the appointment is shown as a ghost element on the mouse cursor. Drop target areas are indicated to the user with a placeholder.

In the “Hours” view, the appointments can be moved to a specific new time, with the placeholder snapping at every 30 minutes. In the “Days” view, the appointment can be moved to a different day. The placeholder indicates the target day. On drop the appointment is moved to that day but keeps its previous start and end hour. The interaction is the same for the “Months” view. The placeholder indicates the target month and, when dropped, the appointment is moved to that month. The start and end hour and start and end day remain the same.

Appointments can be moved between rows. Note that additional coding may be needed to determine whether all calendar users will be able to perform this action.

Users can create new appointments by clicking, dragging and releasing on an empty space in the content area. The control also allows users to change the duration of an appointment by clicking and dragging one side of the appointment container. These two options are only available for desktop devices.

Combined appointments and interval appointments are not draggable.

Drag and drop is only available on supporting browsers.

Drag and drop

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 (SAPUI5 test suite)
Planning Calendar Row (SAPUI5 API reference)
Planning Calendar View (SAPUI5 API reference)
Team Calendar (SAPUI5 sample)

Search

A search is a means of accessing information quickly. If an amount of data is too large for users to find something just by scanning through it, you should consider providing a search function.

Search field

Usage

Use a search field (sap.m.SearchField) if you want to enable users to enter text to search for information. The search field is also the control of choice for filtering down a given amount of information.

Responsiveness

When suggestions are turned on, the suggestion list displays differently depending on the device type.

Size S (Smart Phones)

Clicking the search field opens a new full screen dialog in which items can be selected from a list of suggestions.

Size S

Size M (Tablets)

Suggestions are shown below the search field.

Size M

Size L (Desktops)

Suggestions are shown below the search field.

Size L

Types

SAP Fiori comes with two different search types.

The manual search is triggered explicitly after the user enters text in the search field and clicks the Search button or presses the Enter key.
The live search (also known as “incremental search” or “search-as-you-type”) is triggered by each character that the user enters or deletes. There is a default delay of 400 ms before sending the search data to the back end. This ensures better performance and optimizes user experience.

Queries that are entered are used to search the back-end data for term matches (not case-sensitive). While a live search uses a “contains” approach, a manual search uses a “starts with” approach. “Contains” means that the result needs to match the query only partly to be a valid result. “Starts with” means that full terms of the result need to start with the entered query to be visualized.

Layout

The search input field (or search box) consists of two parts:

The text input, which is left-aligned. Initially, the field shows a placeholder (Search). As soon as the user enters a character, this prompt text disappears. It appears again if the user deletes the entry.
If a manual search is to be implemented, a search button with a magnifier icon is placed on the right side of this input control. The user clicks this button to trigger the search. In live searches, the magnifier icon is also placed here, but it functions more like an additional indicator to signify that this is a search input field. It also functions as an explicit search button if the user wants to search again for a query that has already been entered.

All item attributes defined by the app development team are searched. When the results are displayed, the items found do not necessarily have to show the attribute through which the item was found. The results are displayed in the same list that contained the original item set. Initial grouping and the order of the list are not affected by the search.

When the split screen is used, the search field appears at the top of the master list. In full screen mode, the search field is placed at the top of the page.

Behavior and Interaction

Entering a Search Term

Search terms can be entered easily into the input field. The search box then displays all full-text search terms. There is no line break and no truncation if the query is longer than the input field. Results might also be displayed that do not match the query in their title or subtitle. This might be because details can also be searched for. The user can see the matching terms in the specific details section.

Deleting a Search Term

The user can click the “X” icon ( ) button to remove the text from the field. In the case of the live search, this also resets the search. In a manual search, deleting the search term and then triggering the search resets the search results.

Refreshing

If the Refresh button is available, the user can update the list without triggering a new search. This is usually needed when backend data changes quickly and often.

If the currently selected item is no longer available after the list has been refreshed, the next item in the line is selected. If no next item is available, the first item in the line should be selected next.

Search field with 'Refresh' button

On touch devices, the Refresh icon is not visible in the search field. In this case, Pull Down to Refresh is used instead. The Pull Down to Refresh arrow icon is animated and spins to signal that the user should release it.

Pull to Refresh on a touch device

Information

For information on how to manage leading and trailing white space (blanks) when copying and pasting text into input controls, please see removing leading and trailing white space.

Properties

The following methods are important.

For the live search:

attachLiveChange(oData?, fnFunction, oListener?) Attach event handler fnFunction to the liveChange event of this sap.m.SearchField.
detachLiveChange(fnFunction, oListener) Detach event handler fnFunction from the liveChange event of this sap.m.SearchField.
fireLiveChange(mArguments?) Fire liveChange event to attached listeners.

For the manual search:

attachSearch(oData?, fnFunction, oListener?) Attach event handler fnFunction to the search event of this sap.m.SearchField.
detachSearch(fnFunction, oListener) Detach event handler fnFunction from the search event of this sap.m.SearchField.
fireSearch(mArguments?) Fire search event to attached listeners.

If a Refresh button is needed:

getShowRefreshButton() Getter for property showRefreshButton.
setShowRefreshButton(bShowRefreshButton) Setter for property showRefreshButton.

To show the Search button:

getShowSearchButton() Getter for property showSearchButton.
setShowSearchButton(bShowSearchButton) Setter for property showSearchButton.

To ensure the focus is set to input:

setSelectOnFocus(bSelectOnFocus) Setter for property selectOnFocus.

If the search is triggered automatically when the value of the field is changed (unlike the liveChange event, the change event is not fired for each key press):

attachChange(oData?, fnFunction, oListener?) Attach event handler fnFunction to the change event of this sap.m.SearchField.
detachChange(fnFunction, oListener) Detach event handler fnFunction from the change event of this sap.m.SearchField.
fireChange(mArguments?) Fire change event to attached listeners.

Guidelines

Implement the live search whenever possible.
Use a manual search only if the amount of data is too large and if your app would otherwise run into performance issues.
Show an appropriate prompt text:Search if queries are sent to all connected services, or Search In: if the search is limited to a certain source or providing service.

Resources

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

Elements and Controls

Input Field (guidelines)
Button (guidelines)
Master List (guidelines)
Split Screen (guidelines)
Full Screen (guidelines)
Enterprise Search (guidelines)
Cozy/Compact (guidelines)

Implementation

Search Field (SAPUI5 samples)
Search Field (SAPUI5 API reference)

Feed and Notes

Feeds and notes are commonplace in many SAP Fiori applications. The sap.m.FeedInput control allows users to input and post plain text, while the sap.m.FeedListItem control handles and displays this text. Both can be used individually, but they also complement each other well to create a simple feed or notes control.

Usage

Feed Input

Use the feed input if:

A user needs to input small amounts of text without formatting.
You expect multiple instances, such as notes or feed entries.

Do not use the feed input if:

The user needs to format the text (rich text editor).
You need only a single text box instance. In this case, use the text area (for multiple lines) or the text control (for a single line).

Combination of Both Controls (as Feed or Notes Control)

Use both controls if:

You need a feed to show textual posts.
Your users need to input notes.

Do not use both controls if:

You expect extensive social interaction in the feed.
Users need to reply at item level instead of creating a new post.
You want to display SAP Jam feeds.

In these cases, use the social timeline instead (requires SAP Jam).

Responsiveness

Due to their responsive behavior, both controls can be used in small and large view ports or screens.

For better usability, we highly recommend that you do not stretch the controls across the full width on large screens – 2/3 or even 1/2 works just fine. This can easily be achieved using the grid layout .

Feed – Size S

Feed – Size M

Feed – Size L

When the width of the available space falls below 25 rem (for example, in portrait mode on smartphones), the two controls respond as follows:

If a user image previously appeared in the feed input, it will be omitted in narrow screens to give the text field more space.
If there is no user image, there will be no visual change.

Feed input – Responsiveness

In the feed list item, the user’s name, image, and the time stamp move on top of the text. If there is no image, the name and time stamp are left-aligned together with the text.

Feed list item – Responsiveness – With image

Feed list item – Responsiveness – Without image

Layout

Feed Input

The feed input consists of:

A text input field with a placeholder (input prompt)
Example: Add a comment
A Send button
An optional user image

You can also choose not to show user images at all. In this case, the size of the input area increases automatically.

Feed input – Layout – With user image

Feed input – Layout – With generic user image

Feed input – Layout – Without user image

Feed List Item

The feed list item consists of the user’s name and an optional picture of the user who wrote the note or update. The name can contain a link that triggers a quick overview of the user’s profile data. The actual text written by the user follows the name. Below it is a separate byline that can contain a time stamp and an attribute in the form of free text. This allows you to put in your own attribute, such as Approval, Internal, or External. Both the time stamp and the attribute are optional.

If the name is a link, the picture should also be linked with the same attributes.

Feed list item – With user image and linked name

If the user does not have a picture assigned, a placeholder is shown instead:

Feed list item – With generic user image and linked name

The name (and picture) can also be read-only, that is, without a link:

Feed list item – With user image but without links

If the app does not support user images, they can be omitted:

Feed list item – Without user image but with linked name

Here, too, the name can be read-only:

Feed list item – Without user image and read-only name

It’s also possible to display rich text (formatted text) in the feed list item. This feature should be handled with care as it allows for countless custom layouts.

Please see that you use it responsibly and provide your users with a consistent experience. Only deviate from the default layout and font if absolutely required by the use case.

Example use case: Render URLs as links.

Feed list item – Layout – Rich text

Information

The items in the feed list must be homogeneous. This means that they must contain the same layout and visualization. For example, it is not possible to have a feed containing both linked and plain names, or both user images and default images.

Special Case: Multiple Types of Notes

Apps sometimes need to discern between different types of notes. There is an easy way to allow users to choose which type they want to see or add to the list.

You can place a toolbar containing a select control at the top of the feed input control. From there, users can select the type of notes, such as Internal Notes or External Notes. The list of notes must contain only the type selected. If the user adds a note via the feed input, the type must be set automatically according to the selection.

Interaction – Note Types

Components

The feed input and feed list item do not contain subcontrols. However, you can easily combine them to create a simple feed or notes control.

Although the feed input counts as a single control, the input area inherits its behavior from the sap.m.TextArea control.

Behavior and Interaction

Send Message

Initially, the feeder contains a placeholder (input prompt), and the Send button is disabled, with reduced opacity.

Clicking into the input field puts the focus on the field and allows to start typing.

When the user starts to type, the placeholder disappears and the Send button becomes active and more prominent.

If the available width is below 25 rem (for example, in portrait mode on a smartphone), the picture is removed.

To send the text, the user must explicitly click the Send button. Pressing Enter on the keyboard (on-screen or physical) results in a line break.

Feed input – Behavior

Show More Text

When the text exceeds a certain number of characters (you can overwrite the default value), the rest of the text is truncated and a MORE link appears after the truncated section.

The MORE link indicates the possibility of expanding the section of the feed list item itself. Hovering over the link underlines it.

Show Less Text

When the user expands the text, the name of this link changes to LESS, but still behaves the same way as before.

Both texts for the “MORE” / “LESS” links can be modified to suit a particular use case. There is a possibility to use uppercase, lowercase or a mix of them.

Feed and Notes in Tables

In tables, users sometimes need to see if an object has a comment (or feed or note) without further navigation, and even be able to add/edit right from the table.

Add an additional column, named according to the type of user input, such as Comment, Note, or Feed.

Place a link inside each cell with the appropriate action (row: Comment, link: Comment/ row: Feed, link: Post).
If there can be more than one item, add a counter after the text as well (see example on the right).

This solution works with every table control.

Feed and notes in tables (1)

Optional:
Depending on the use case, it might help users if they can see the latest note. The responsive table allows the feed list item (sap.m.FeedListItem) to be used inside a cell.

Reduce the property “maxCharacters” to an amount that your table can handle.
Note that once the maximum number of characters has been reached, a MORE link allows users to expand the text. Technically, this is no problem for the responsive table, but you need to ensure that the layout of your page allows this kind of expansion.

Place a link below the feed list item to allow users to add something (as described above).

Feed and notes in tables (2)

When the user clicks a link, such as Comment or Note, display a dialog showing all comments (notes, feed entries, and so on) along with possible actions, such as Add or Edit, depending on your use case.

There are several ways to show notes (comments, feed entries, and so on) in a dialog:

You can use the feed list item (and feed input) as described in this article.
If only one single note is allowed, you can use the text area.
For a large feed, you can use the timeline control (SAP Jam is required for social features).

Actions On Feed List Items

Applications can define actions that users can perform on individual feed posts. The two most typical actions are Edit and Delete. Other actions can be introduced as required by the use case. To keep the feed as lightweight as possible, don’t overwhelm users with too many actions or complicated actions (max. 5 per post).

Interaction - Actions

Styles

By default, feed entries are separated by divider lines. We recommend that these separators remain enabled, since they help distinguish between individual posts. However, if your list is expected to hold only a handful of entries, you can disable the separators by setting the showSeparators property at list level (not at list item level) to none.

Guidelines

Because the feed list item is built on the basis of the standard list item, it inherits multiple properties that may not make sense in a feed use case.

Use only properties that are described in this article. Especially making the entire feed list item clickable can lead to functional issues and usability problems.

Don’t stretch the feed input or the feed list items across large screens (size L and beyond). This will have a negative effect on usability and readability. Instead, only use 1/3 or even 1/2 of the screen. Implement this with the grid layout .

If you display formatted text (rich text) in the feed list item, use formatting that is beneficial to users, not decorative formatting. Use formatting responsibly, and provide your users with a consistent experience. Deviate from the default layout and font only if absolutely required by the use case (example: render URLs as links).

Resources

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

Elements and Controls

No links.

Implementation

Feed Input (SAPUI5 samples)
Feed List Item (SAPUI5 samples)
Feed (SAPUI5 samples)
Feed Input (SAPUI5 API reference)
Feed List Item (SAPUI5 API reference)

Date/Time Picker

The date/time picker allows users to select date and time values in a combined input.

Usage

Use the date/time picker if:

You need a combined date and time input control.

Do not use the date time picker if:

You want to use either a date or a time value. In this case, use the date picker or the time picker instead.

Responsiveness

The date/time picker runs on all form factors and fully adapts to all devices.

Date/time picker - Compact mode

Date/time picker - Cozy mode

Behavior and Interaction

Selecting Date and Time Values

Sizes M and L/XL

The date/time picker appears as a popover when the user clicks a date (input field) on the calendar. The user can then select the desired date from the calendar, and the time from the rotating wheel. For the time, it’s possible to select hours, minutes, and even seconds.

When the user clicks the OK button, the popover closes and the selected date and time appear in the input field. When the user selects Cancel, the action is aborted and the input field remains unchanged.

Date/time picker – Entering data with input and picker

Size S and Mobile Size

On smaller devices, the user can choose the date and time value in arbitrary order by tapping the segmented button on top of the screen. Be aware that the popover is superimposed on the input field during the selection process for mobile/S sizes.

The user can select the desired date from the calendar, and the time from the rotating time wheel. For the time, it’s possible to select hours, minutes, and even seconds. Clicking a date in the calendar automatically takes the user to the time selection screen.

When the user selects OK, the popover closes and the selected date and time appear in the input field. When the user selects Cancel, the action is aborted and the input field remains unchanged.

Date/time picker - Smartphone view

Styles

Value States

The Date/Time picker supports the following value states:

Regular
Success
Warning
Error
Information

For the Warning, Error and Information states, there are additional messages available to provide hints for the user.

For more information, see How to Use Semantic Colors.

Date/time picker - Value states

Guidelines

Date Picker and Time Picker

In general, we recommend separating the date/time picker controls as the time picker supports the mask input function and the date picker allows the user to enter date in different formats. This makes it easier and more convenient for the user to enter the desired values. For additional guidelines and information on the individual controls, see the resources section below.

Default Values

Independently of the chosen control, set the default values of the date/time picker carefully to avoid unnecessary scrolling. It often makes sense to set the default for the time to the full or half hour, setting the minutes to 00 or 30. Sometimes, it may also make sense to use the current time and date.

Formatting Dates and Times

For guidelines and information on the SAPUI5 date formatters, see formatting dates.

For guidelines and information on the SAPUI5 time formatters, see formatting times.

Setting Steps

You can set intervals for the minutes and seconds on the slider (properties: minutesStep and/or secondsStep). For example, if you set the seconds step to “5”, the slider offers “00”, “05”, “10”, “15”, and so on.

Time Zone

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

Properties

AM and PM are locale-dependent. The locale can be set using the property localeId.

You can set the display format (property: displayFormat) to define the format in which the time input field and the time picker dropdown display the time.

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

Time Picker (guidelines)
Date Picker (guidelines)
Formatting Time (guidelines)
Formatting Dates (guidelines)

Implementation

Date Time Picker (SAPUI5 samples)
Date Time Picker (SAPUI5 API reference)

Multi-Input Field

A multi-input field allows the user to enter multiple values, which are displayed as tokens. To help the user enter a valid value, you can enable the suggestions feature and the value help option.

Usage

Use the multi-input field if:

You want the user to select multiple ranges (with the value help option and the value help dialog).
The dataset to choose from is expected to increase over time (for example, to more than 200 values).
You need to provide the value help option to help users select or search multiple business objects.
You want to enable users to add custom values.

Do not use the multi-input field if:

You want the user to select one entry only. In this case, use the input field or combo box instead.
You want the user to select from a pre-defined set of options only. In this case, use the multi-combo box instead.

Information

For more information on which selection control to choose, see the selection control overview.

Responsiveness

Size S

Cozy mode.
When the user clicks the multi-input field, a new full screen dialog opens. After clicking the input field and typing, the suggestions can be selected. When the user makes a selection, the dialog closes and the token is displayed.
The user can review the tokens by swiping them to the left or right.

Suggestions on a smartphone (size S)

Users can review tokens by swiping left and right on touch devices

Size M

Cozy mode.
The suggestions appear below or above the multi-input field.
The user can review tokens by swiping them to the left or right.

Suggestions on a tablet (size M)

Size L

Compact mode.
The suggestions appear below or above the multi-input field.
The user can review tokens by pressing the right or left arrows on the keyboard.

Suggestions on a desktop (size L)

Types

The input types of the multi-input field are identical to those of the input field.

Behavior and Interaction

Adding a Token

A token can be added using suggestions or value help. As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. The user can accept the autocompleted value by pressing ENTER. The autocomplete property is set by default if suggestions are available, but can also be switched off.

When an item is selected from the suggestions dropdown, the corresponding token is created, and the input field is ready for the next entry. Tokens are placed next to each other on one line.

Warning

The typeahead input feature is not available for Android devices.

Developer Hint

Values that are entered can also be tokenized when the user presses ENTER. The app development team can perform a custom validation of the entered data and decide whether a token should be created.

Adding tokens

Adding a second token

Information

For information on how to manage leading and treading whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Reviewing Tokens

If tokens have been selected, and the input field is not in focus, the input field displays as many tokens as possible in the available space. If more tokens have been selected, an [n] More label indicates the number of hidden tokens. The tokens in the input field appear in the order in which they were selected.

Clicking the [n] More label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its delete icon.

Multi-input field - 'n More' label (desktop)

Multi-input field - 'n More' label (phone)

If the length of the last selected token exceeds the width of the input field, a label [n] Item/s is shown when the field is not in focus.

Clicking the [n] Item/s label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its delete icon.

If there is only one token in the input field and its length exceeds the width of the input field, the text is truncated. Clicking the token opens a popover below the input field, in which the full text of the token is shown.

Multi-input field - '1 Item' case (desktop)

Multi-input field - 'n Items' label (desktop)

In the input field itself, the user can review tokens by using the left or right cursor keys on a desktop, or by swiping to the left or right on a smartphone or tablet.

Left/right keyboard cursor

Swiping left and right on a touch device

Deleting Tokens

The user can delete tokens by pressing the Backspace or Del button (when selected) on a desktop’s keyboard, or by tapping the Delete icon on a mobile device.

Deleting tokens

Using Value Help

You can enable the value help option to provide a more advanced dialog for finding the relevant business object. Two dialogs can be used at present:

Select dialog (simple)
Value help dialog (complex)

Value help with select dialog

Value help with value help dialog

Filtering

When the user starts typing in the input field, the list is filtered. Only items that match the character or characters entered are shown in the dropdown list. The default filtering method is “starts with per term”, which matches the beginning of each word in an item’s text.

In addition, application developers can set a custom filtering method “starts with” or “contains” (method: setFilterFunction). The “starts with” approach filters only for items where the beginning of the label matches the query entered. The “contains” approach searches the full label for a match.

As a visual hint for the user, the matched characters are highlighted (bold) in the option list items. The highlighting works on the basis of “starts with per term”, regardless of the filtering method.

Multi-input field - Default filtering, autocomplete in the input field is switched off

Copying and Pasting Data from a Spreadsheet or Text File

The multi-input field can handle paste actions containing multiple items, such as items that have been selected in a column of a spreadsheet or text file. The user simply selects a whole column in the spreadsheet, copies it, and then pastes it from the clipboard into the multi-input field. Each item is represented as a token. If a single value is copied and pasted into the field, it is shown as a text value, as further editing might be required before it is converted into a token.

Grouping

You can group the items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

The column headers within the tabular suggestion list remain in place when the list is scrolled (“sticky” behavior).

Multi-input with grouped suggestions

Multi-input with grouped tabular suggestions

Due to a technical limitation, the group headers are not visible when clicking on the n More text.

Group headers not shown when clicking on 'n More' items

Styles

The following images show how the states of the multi-input field are styled.

Unselected

Unselected with predefined placeholder

Unselected on hover

In focus

Selected items shown as tokens

Expanded multi-selection

Error

Warning

Success

Information

For details on the different states, see UI Element States.

For more information on semantic colors for value states, see How to Use Semantic Colors.

Guidelines

Give the control a width that is appropriate for the range of values that are going to be entered. Try to avoid setting a fixed width on this control. Instead, embed it in a proper layout (such as a form, simple form, or grid layout) and work with the layout data property.
Provide meaningful labels for all input fields. Do not use the placeholder as a replacement for the label. The placeholder should only provide an additional hint.
The multi-input field can currently contain tokens and one free text value. If you allow only validated values, display an error or warning when the user tries to leave the field to indicate that the value entered is invalid, or remove the value.
If users try to select an item that has been selected before, we recommend setting an error state and providing a meaningful message.

Multi-input - Error state for an item that has already been selected

You can use the layout options of the form to add the unit of measurement (UoM) after the multi-input control. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

Developer Hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

The multi-input field can be used in the grid table, analytical table and tree table as well, as condensed mode is already supported, both for desktop and mobile (tablets).

Multi-input field in the grid table in condensed mode

Properties

Since the multi-input field is derived from the input field, refer to the properties in the input field article.

Resources

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

Elements and Controls

Multi-Combo Box (guidelines)
Input (guidelines)
Combo Box (guidelines)
Select (guidelines)
Select Dialog (guidelines)
Value Help Dialog (guidelines)
Tokenizer (guidelines)

Implementation

Multi Input (SAPUI5 samples)
Multi Input (SAPUI5 API reference)

Input Field

A text input field allows users to enter and edit text or numeric values in one line. To help users enter a valid value, you can enable the autocomplete suggestion feature and the value help option.

Usage

Use the input field if:

The user needs to enter a short, single-line text or number.
The user needs to enter a password, URL, phone number, or email address.
The user needs to select a single item from a large amount of data (for example, more than 200 items).
The user needs to find an object by searching for more than one attribute, such as an ID, city, and customer name. Use this control in combination with the autocomplete suggestion feature and value help option. For a small set of values (for example, fewer than 20 items), consider using the select control. Otherwise, use the combo box (for 20-200 items).

Do not use the input field if:

The user needs to enter dates and times. In this case, use the date picker, date range selection, or date/time picker.
The user needs to enter long texts. In this case, use the text area.
The user needs to carry out a search. In this case, use the search field.
The user needs to select multiple values. In this case, use the multi-combo box (for fewer than 200 items) or the multi-input field (for more than 200 items).

Information

For more information on which selection control to choose, see the selection control overview.

Responsiveness

In the examples below, the input field is shown in combination with the tabular autocomplete feature for different device sizes.

Note that when tabular suggestions are used, the column headers stay sticky when scrolling within the suggestion list.

Size S (Smartphones)

Cozy mode:

When the user clicks the input field, a new full screen dialog opens in which suggested items can be selected. Here, the pop-in feature of the responsive table is used.

Tabular autocomplete suggestion feature on a smartphone

Size M (Tablets)

Cozy mode:

The pop-in feature of the responsive table is used here, and defined columns are wrapped into a new line due to the limited space available.

Tabular autocomplete suggestion feature on a tablet

Tabular autocomplete suggestion with sticky header

Size L (Desktops)

Compact mode:

The full table is shown by the suggest feature.

Tabular autocomplete suggestion feature on a desktop

Types

Six input types are currently supported (API). Be sure to select the correct type for your use case. Depending on the input type, a different keyboard layout is displayed on a mobile device (see some sample input types).

Note: The control does not provide validation based on the type. The app development team must implement format validation. If binding is used, validation is carried out by the model, but error handling must still be implemented on the UI side.

Text (default)

Input type text – Keyboard layout on a smartphone

Number

Input type number – Keyboard layout on a smartphone

Email

Input type email – Keyboard layout on a smartphone

URL

Input type URL – Keyboard layout on a smartphone

Telephone Number

Input type telephone number – Keyboard layout on a smartphone

Password

Input type password – Keyboard layout on a smartphone

Some types, such as number or telephone number, can be used together with mask input for better guidance.

Examples of input with different number masks

Behavior and Interaction

Entering Text Using the Autocomplete Feature

Have a look at the interaction flow below:

Entering Text Using the Value Help Dialog

Have a look at the interaction flow below:

Value Help Dialog on Mobile

Value Help Dialog on Desktop

Information

For information on how to manage leading and trailing white space (blanks) when copying and pasting text into input controls, see removing leading and trailing white space.

Styles

An input field can have the following styles. For more information, see UI Element States.

Input field states

Properties

Value State and Value State Message

The input control offers the four value states listed below, for which you can show an additional value state text message when the focus is on the input field.

Error
Warning
Success (no message is available for this state)
Information

For more guidance on when to use which state, see How to Use Semantic Colors.

Input field in semantic colors with message box below

Enabled, Read-only and Disabled states

The input field has three states (see examples of input states):

Enabled: This is the default setting.
Read-only: The input field isn’t shown, just the value. This is used in display-only forms.
Disabled: The input field is shown with a visual indication that editing isn’t possible (for example, because the user isn’t authorized to make changes).

Input Field - Enabled

Input Field - Read only

Input Field - Disabled

Required

Use this property to indicate that user input is required. Set the property for the specific input field to ensure that the asterisk is shown in front of the label.

Required input field

Maximum Length

Use this property to set the maximum number of characters allowed. There is no limit by default.

Placeholder

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

Placeholder

Description

You can provide an additional description on the input field, for example, for units or currency. The width of the input field and description is distributed equally by default. Although the default setting is 50%, you can change this with the fieldWidth property.

Input description

Width

The width of the input field is set to 100% by default. Input fields are usually used in forms, where the width is determined by the form element or container that the input field is embedded in. Instead of defining a fixed width, we recommend working with proper layout containers, like the form, simple form, and responsive grid layout, and with the layout data property, where the width is defined by the 12-column approach.

Text Alignment

The input field offers six types of alignment for text values (API):

Begin
Center
End
Initial (default): Browser-configured alignment is used
Left
Right

Value Help

To help the user find the correct value, you can enable the value help option (property: showValueHelp). By enabling this option, a small value help icon ()is displayed in the input field on the right-hand side. Once this option is enabled, the click event can be registered and one of the following displayed:

Select dialog (simple)
Value help dialog (complex)

If you want to force the user to select only existing values, you can enable the value-help-only option (see an example). In this case, the user cannot enter text in the input field. Instead, the value must be selected from the list of suggestions, or chosen using the select dialog or value help dialog.

Input Field with value help

Value help only

The values can also be pasted into the input field by copying and pasting, or dragging and dropping, if the user prefers. In this case, the values are automatically transformed into conditional expressions. For example: Copying values “1234” and “5678” leads to the token generation “=1234” and “=5678”. Additionally, these values are shown in the conditions tab of the value help dialog.

Input Assistance

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

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

Autocomplete Suggestions

The input control offers three different types of autocomplete suggestions: single, two-value, and tabular. The width of the suggestion box and the input field are set by default, but you can change them using the maxSuggestionWidth property. The position of the suggestion box depends on the space available below the control. If there is not enough space, the suggestion box is shown above the control.

As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. The user can accept the autocompleted value by pressing ENTER. The autocomplete property is set by default if suggestions are available, but can also be switched off.

Warning

The typeahead input feature is not available on Android devices

Single Value with Autocomplete

Single-value autocomplete displays a list of suggestions with one left-aligned value. As a base for the aggregation suggestionItems, sap.ui.core.Item is used.

Use the single-value autocomplete feature if you want to search by only one attribute, such as an ID or a customer name.

See this live example of single-value autocomplete suggestions.

Single-value autocomplete suggestion feature

Two Values with Autocomplete

The two-value autocomplete suggestion feature displays two attributes of a business object, such as a customer and an ID. As a base for the aggregation of suggestionItems, sap.ui.core.ListItem is used.

The text property is displayed first, and is left-aligned. The additionalText property is right-aligned. The first text property is autocompleted in the input field.

Use the two-value autocomplete feature if you want to search by two attributes. This ensures that the search is carried out for both attributes.

See this live example of two-value autocomplete suggestions.

Two-value autocomplete suggestion feature

Tabular Autocomplete

This autocomplete feature displays the values in a table layout. Use the tabular autocomplete feature if you need to display more than two attributes.

For input fields in a tabular view, we recommend using a maximum of 4 columns. Focus on columns that are really relevant for the use case.

To use the tabular autocomplete feature, use the suggestionColumns aggregation to define the columns and the correct responsive behavior for the pop-in. Define appropriate responsive behavior for sizes S and M. For more information, see the article on the responsive table.

With the showTableSuggestionValueHelp property, you can offer a Show All Items button at the end of the suggest result list. Because the number of results in the suggest functionality is limited, this option helps the user find the relevant item via an alternative dialog:

Select dialog (simple)
Value help dialog (complex)

The width of the columns is distributed equally by default. To avoid truncation, accurately estimate the primary attribute length and set a minimum width for this column.

The column headers remain in place when the user scrolls through the suggestion list (“sticky” behavior).

See a live example of tabular autocomplete suggestions.

Tabular autocomplete

Grouping

You can group the items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

Input with grouped suggestions

Input with grouped tabular suggestions

Guidelines

Always provide a meaningful label for any input field, and use the least complex control (such as select instead of value help). Use more intricate controls only if the use case really requires it. Where appropriate, help users by providing mask input or placeholder texts.

Maximum Columns

For input fields in a tabular view, we recommend using a maximum of 4 columns.

Maximum Length

Limit the length of the input field. For example, if you don’t want users to enter more than 5 characters, set the maximum length to 5. The maximum permissible character length is not defined by default. If the back-end system has a limit, ensure that you set this property accordingly.

Note that this parameter is not compatible with the input type sap.m.InputType.Number. If the input type is set to Number, the value of the maxLength property is ignored.

Placeholder

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

Description

The description field should be used, for example, for displaying units or currency. Do not use a description for help text or as a label replacement. Note that the description is not placed in a new line in size S. Therefore, only use the description property for small input fields with a short description.

Width

Avoid setting a fixed width, but rather embed it in a proper layout (such as a form, simple form, or grid layout) and use the layout data property to define the responsive behavior for sizes S, M, and L:
- Simple form – See a live example of a simple form.
- Form – See a live example of a form.
- Grid layout – See a live example of a grid layout.
Ensure an appropriate width for the range of values to be entered for the sizes S, M, and L. Keep in mind that word length can vary between languages, so take localization into account.

Editable and Enabled States

Editable

Property settings: editable = true, enabled = true

The input control is enabled and editable by default. Set the control to editable to allow the user to enter a value.

Not Editable

Property settings: editable = false, enabled = true

Use this state, for example, to display data only.

Disabled

Property settings: editable = not relevant, enabled = false

Set the control to disabled in an edit scenario to indicate that the user cannot change the control, for example, due to missing access rights or previous conditions not having been fulfilled or selected.

Text Align

Align left if:

Text is used. Also use left alignment for a phone number, URL, password, and email address.

Align right if:

Amounts and decimal numbers are used.
Values need to be added and compared.

Value Help

Show the value help option to help the user select the correct value (such as a customer ID) from a large dataset via the:

Use this option in combination with the autocomplete suggestion feature.

When the user clicks the value help icon, the data entered into the input field must be transferred to the processing dialog so that the user does not have to enter the search term again. Likewise, data entered in the processing dialog must be transferred back to the input field.

Creating and Editing Objects

Sometimes a new object needs to be created if the user cannot find a specific item via autocomplete or value help. In this case, we recommend that you place the New action next to the input field.

If you want the user to be able to edit a selected object directly, you should place the Edit link next to the input field.

If both actions are needed, they should be toggled based on the content of the input field. If a valid object is selected, you should display Edit. If the input field is empty or the object is not valid, you should display New. This pattern can also be applied for the multi-input field, combo box, multi-combo box, and select controls.

Input field – New action

Input field – Edit action

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 Dialog (guidelines)
Value Help Dialog (guidelines)
Combo Box (guidelines)
Select (guidelines)
Multi-Input Field (guidelines)
Date Range (guidelines)
Date/Time Picker (guidelines)
Multi-Combo Box (guidelines)
Dialog (guidelines)
How To Use Semantic Colors (guidelines)

Implementation

Input Field (SAPUI5 samples)
Input Field (SAPUI5 API reference)

Input Field

A text input field allows users to enter and edit text or numeric values in one line. To help users enter a valid value, you can enable the autocomplete suggestion feature and the value help option.

Usage

Use the input field if:

The user needs to enter a short, single-line text or number.
The user needs to enter a password, URL, phone number, or email address.
The user needs to select a single item from a large amount of data (for example, more than 200 items).
The user needs to find an object by searching for more than one attribute, such as an ID, city, and customer name. Use this control in combination with the autocomplete suggestion feature and value help option. For a small set of values (for example, fewer than 20 items), consider using the select control. Otherwise, use the combo box (for 20-200 items).

Do not use the input field if:

The user needs to enter dates and times. In this case, use the date picker, date range selection, or date/time picker.
The user needs to enter long texts. In this case, use the text area.
The user needs to carry out a search. In this case, use the search field.
The user needs to select multiple values. In this case, use the multi-combo box (for fewer than 200 items) or the multi-input field (for more than 200 items).

Information

For more information on which selection control to choose, see the selection control overview.

Responsiveness

In the examples below, the input field is shown in combination with the tabular autocomplete feature for different device sizes.

Note that when tabular suggestions are used, the column headers stay sticky when scrolling within the suggestion list.

Size S (Smartphones)

Cozy mode:

When the user clicks the input field, a new full screen dialog opens in which suggested items can be selected. Here, the pop-in feature of the responsive table is used.

Tabular autocomplete suggestion feature on a smartphone

Size M (Tablets)

Cozy mode:

The pop-in feature of the responsive table is used here, and defined columns are wrapped into a new line due to the limited space available.

Tabular autocomplete suggestion feature on a tablet

Tabular autocomplete suggestion with sticky header

Size L (Desktops)

Compact mode:

The full table is shown by the suggest feature.

Tabular autocomplete suggestion feature on a desktop

Types

Six input types are currently supported (API). Be sure to select the correct type for your use case. Depending on the input type, a different keyboard layout is displayed on a mobile device (see some sample input types).

Note: The control does not provide validation based on the type. The app development team must implement format validation. If binding is used, validation is carried out by the model, but error handling must still be implemented on the UI side.

Text (default)

Input type text – Keyboard layout on a smartphone

Number

Input type number – Keyboard layout on a smartphone

Email

Input type email – Keyboard layout on a smartphone

URL

Input type URL – Keyboard layout on a smartphone

Telephone Number

Input type telephone number – Keyboard layout on a smartphone

Password

Input type password – Keyboard layout on a smartphone

Some types, such as number or telephone number, can be used together with mask input for better guidance.

Examples of input with different number masks

Behavior and Interaction

Entering Text Using the Autocomplete Feature

Have a look at the interaction flow below:

Entering Text Using the Value Help Dialog

Have a look at the interaction flow below:

Value Help Dialog on Mobile

Value Help Dialog on Desktop

Information

For information on how to manage leading and trailing white space (blanks) when copying and pasting text into input controls, see removing leading and trailing white space.

Styles

An input field can have the following styles. For more information, see UI Element States.

Input Field States

Properties

Value State and Value State Message

The input control offers the four value states listed below, for which you can show an additional value state text message when the focus is on the input field.

Error
Warning
Success (no message is available for this state)
Information

For more guidance on when to use which state, see How to Use Semantic Colors.

Input field in semantic colors with message box below

Enabled, Read-only and Disabled states

The input field has three states (see examples of input states):

Enabled: This is the default setting.
Read-only: The input field isn’t shown, just the value. This is used in display-only forms.
Disabled: The input field is shown with a visual indication that editing isn’t possible (for example, because the user isn’t authorized to make changes).

Input Field - Enabled

Input Field - Read only

Input Field - Disabled

Required

Use this property to indicate that user input is required. Set the property for the specific input field to ensure that the asterisk is shown in front of the label.

Required input field

Maximum Length

Use this property to set the maximum number of characters allowed. There is no limit by default.

Placeholder

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

Placeholder

Description

You can provide an additional description on the input field, for example, for units or currency. The width of the input field and description is distributed equally by default. Although the default setting is 50%, you can change this with the fieldWidth property.

Input description

Width

The width of the input field is set to 100% by default. Input fields are usually used in forms, where the width is determined by the form element or container that the input field is embedded in. Instead of defining a fixed width, we recommend working with proper layout containers, like the form, simple form, and responsive grid layout, and with the layout data property, where the width is defined by the 12-column approach.

Text Alignment

The input field offers six types of alignment for text values (API):

Begin
Center
End
Initial (default): Browser-configured alignment is used
Left
Right

Value Help

To help the user find the correct value, you can enable the value help option (property: showValueHelp). By enabling this option, a small value help icon is displayed in the input field on the right-hand side. Once this option is enabled, the click event can be registered and one of the following displayed:

Select dialog (simple)
Value help dialog (complex)

If you want to force the user to select only existing values, you can enable the value-help-only option (see an example). In this case, the user cannot enter text in the input field. Instead, the value must be selected from the list of suggestions, or chosen using the select dialog or value help dialog.

Input Field with value help

Value help only

The values can also be pasted into the input field by copying and pasting, or dragging and dropping, if the user prefers. In this case, the values are automatically transformed into conditional expressions. For example: Copying values “1234” and “5678” leads to the token generation “=1234” and “=5678”. Additionally, these values are shown in the conditions tab of the value help dialog.

Input Assistance

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

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

Autocomplete Suggestions

The input control offers three different types of autocomplete suggestions: single, two-value, and tabular. The width of the suggestion box and the input field are set by default, but you can change them using the maxSuggestionWidth property. The position of the suggestion box depends on the space available below the control. If there is not enough space, the suggestion box is shown above the control.

As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. The user can accept the autocompleted value by pressing ENTER. The autocomplete property is set by default if suggestions are available, but can also be switched off.

Warning

The typeahead input feature is not available on Android devices

Single Value with Autocomplete

Single-value autocomplete displays a list of suggestions with one left-aligned value. As a base for the aggregation suggestionItems, sap.ui.core.Item is used.

Use the single-value autocomplete feature if you want to search by only one attribute, such as an ID or a customer name.

See this live example of single-value autocomplete suggestions.

Single-value autocomplete suggestion feature

Two Values with Autocomplete

The two-value autocomplete suggestion feature displays two attributes of a business object, such as a customer and an ID. As a base for the aggregation of suggestionItems, sap.ui.core.ListItem is used.

The text property is displayed first, and is left-aligned. The additionalText property is right-aligned. The first text property is autocompleted in the input field.

Use the two-value autocomplete feature if you want to search by two attributes. This ensures that the search is carried out for both attributes.

See this live example of two-value autocomplete suggestions.

Two-value autocomplete suggestion feature

Tabular Autocomplete

This autocomplete feature displays the values in a table layout. Use the tabular autocomplete feature if you need to display more than two attributes.

For input fields in a tabular view, we recommend using a maximum of 4 columns. Focus on columns that are really relevant for the use case.

To use the tabular autocomplete feature, use the suggestionColumns aggregation to define the columns and the correct responsive behavior for the pop-in. Define appropriate responsive behavior for sizes S and M. For more information, see the article on the responsive table.

With the showTableSuggestionValueHelp property, you can offer a Show All Items button at the end of the suggest result list. Because the number of results in the suggest functionality is limited, this option helps the user find the relevant item via an alternative dialog:

Select dialog (simple)
Value help dialog (complex)

The width of the columns is distributed equally by default. To avoid truncation, accurately estimate the primary attribute length and set a minimum width for this column.

See a live example of tabular autocomplete suggestions.

Tabular autocomplete

Grouping

You can group the items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

Input with grouped suggestions

Input with grouped tabular suggestions

Guidelines

Always provide a meaningful label for any input field, and use the least complex control (such as select instead of value help). Use more intricate controls only if the use case really requires it. Where appropriate, help users by providing mask input or placeholder texts.

Maximum Columns

For input fields in a tabular view, we recommend using a maximum of 4 columns.

Maximum Length

Limit the length of the input field. For example, if you don’t want users to enter more than 5 characters, set the maximum length to 5. The maximum permissible character length is not defined by default. If the back-end system has a limit, ensure that you set this property accordingly.

Note that this parameter is not compatible with the input type sap.m.InputType.Number. If the input type is set to Number, the value of the maxLength property is ignored.

Placeholder

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

Description

The description field should be used, for example, for displaying units or currency. Do not use a description for help text or as a label replacement. Note that the description is not placed in a new line in size S. Therefore, only use the description property for small input fields with a short description.

Width

Avoid setting a fixed width, but rather embed it in a proper layout (such as a form, simple form, or grid layout) and use the layout data property to define the responsive behavior for sizes S, M, and L:
- Simple form – See a live example of a simple form.
- Form – See a live example of a form.
- Grid layout – See a live example of a grid layout.
Ensure an appropriate width for the range of values to be entered for the sizes S, M, and L. Keep in mind that word length can vary between languages, so take localization into account.

Editable and Enabled States

Editable

Property settings: editable = true, enabled = true

The input control is enabled and editable by default. Set the control to editable to allow the user to enter a value.

Not Editable

Property settings: editable = false, enabled = true

Use this state, for example, to display data only.

Disabled

Property settings: editable = not relevant, enabled = false

Set the control to disabled in an edit scenario to indicate that the user cannot change the control, for example, due to missing access rights or previous conditions not having been fulfilled or selected.

Text Align

Align left if:

Text is used. Also use left alignment for a phone number, URL, password, and email address.

Align right if:

Amounts and decimal numbers are used.
Values need to be added and compared.

Value Help

Show the value help option to help the user select the correct value (such as a customer ID) from a large dataset via the:

Use this option in combination with the autocomplete suggestion feature.

When the user clicks the value help icon, the data entered into the input field must be transferred to the processing dialog so that the user does not have to enter the search term again. Likewise, data entered in the processing dialog must be transferred back to the input field.

Creating and Editing Objects

Sometimes a new object needs to be created if the user cannot find a specific item via autocomplete or value help. In this case, we recommend that you place the New action next to the input field.

If you want the user to be able to edit a selected object directly, you should place the Edit link next to the input field.

If both actions are needed, they should be toggled based on the content of the input field. If a valid object is selected, you should display Edit. If the input field is empty or the object is not valid, you should display New. This pattern can also be applied for the multi-input field, combo box, multi-combo box, and select controls.

Input field – New action

Input field – Edit action

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 Dialog (guidelines)
Value Help Dialog (guidelines)
Combo Box (guidelines)
Select (guidelines)
Multi-Input Field (guidelines)
Date Range (guidelines)
Date/Time Picker (guidelines)
Multi-Combo Box (guidelines)
Dialog (guidelines)
How To Use Semantic Colors (guidelines)

Implementation

Input Field (SAPUI5 samples)
Input Field (SAPUI5 API reference)

Multi-Input Field

A multi-input field allows the user to enter multiple values, which are displayed as tokens. To help the user enter a valid value, you can enable the suggestions feature and the value help option.

Usage

Use the multi-input field if:

You want the user to select multiple ranges (with the value help option and the value help dialog).
The dataset to choose from is expected to increase over time (for example, to more than 200 values).
You need to provide the value help option to help users select or search multiple business objects.
You want to enable users to add custom values.

Do not use the multi-input field if:

You want the user to select one entry only. In this case, use the input field or combo box instead.
You want the user to select from a pre-defined set of options only. In this case, use the multi-combo box instead.

Information

For more information on which selection control to choose, see the selection control overview.

Responsiveness

Size S

Cozy mode.
When the user clicks the multi-input field, a new full screen dialog opens. After clicking the input field and typing, the suggestions can be selected. When the user makes a selection, the dialog closes and the token is displayed.
The user can review the tokens by swiping them to the left or right.

Suggestions on a smartphone (size S)

Users can review tokens by swiping left and right on touch devices

Size M

Cozy mode.
The suggestions appear below or above the multi-input field.
The user can review tokens by swiping them to the left or right.

Suggestions on a tablet (size M)

Size L

Compact mode.
The suggestions appear below or above the multi-input field.
The user can review tokens by pressing the right or left arrows on the keyboard.

Suggestions on a desktop (size L)

Types

The input types of the multi-input field are identical to those of the input field.

Behavior and Interaction

Adding a Token

A token can be added using suggestions or value help. As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. The user can accept the autocompleted value by pressing ENTER. The autocomplete property is set by default if suggestions are available, but can also be switched off.

When an item is selected from the suggestions dropdown, the corresponding token is created, and the input field is ready for the next entry. Tokens are placed next to each other on one line.

Warning

The typeahead input feature is not available for Android devices.

Developer Hint

Values that are entered can also be tokenized when the user presses ENTER. The app development team can perform a custom validation of the entered data and decide whether a token should be created.

Adding tokens

Adding a second token

Information

For information on how to manage leading and treading whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Reviewing Tokens

If tokens have been selected, and the input field is not in focus, the input field displays as many tokens as possible in the available space. If more tokens have been selected, an [n] More label indicates the number of hidden tokens. The tokens in the input field appear in the order in which they were selected.

Clicking the [n] More label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its delete icon.

Multi-input field - 'n More' label (desktop)

Multi-input field - 'n More' label (phone)

If the length of the last selected token exceeds the width of the input field, a label [n] Item/s is shown when the field is not in focus.

Clicking the [n] Item/s label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its delete icon.

If there is only one token in the input field and its length exceeds the width of the input field, the text is truncated. Clicking the token opens a popover below the input field, in which the full text of the token is shown.

Multi-input field - '1 Item' case (desktop)

Multi-input field - 'n Items' label (desktop)

In the input field itself, the user can review tokens by using the left or right cursor keys on a desktop, or by swiping to the left or right on a smartphone or tablet.

Left/right keyboard cursor

Swiping left and right on a touch device

Deleting Tokens

The user can delete tokens by pressing the Backspace or Del button (when selected) on a desktop’s keyboard, or by tapping the Delete icon on a mobile device.

Deleting tokens

Using Value Help

You can enable the value help option to provide a more advanced dialog for finding the relevant business object. Two dialogs can be used at present:

Select dialog (simple)
Value help dialog (complex)

Value help with select dialog

Value help with value help dialog

Filtering

When the user starts typing in the input field, the list is filtered. Only items that match the character or characters entered are shown in the dropdown list. The default filtering method is “starts with per term”, which matches the beginning of each word in an item’s text.

In addition, application developers can set a custom filtering method “starts with” or “contains” (method: setFilterFunction). The “starts with” approach filters only for items where the beginning of the label matches the query entered. The “contains” approach searches the full label for a match.

As a visual hint for the user, the matched characters are highlighted (bold) in the option list items. The highlighting works on the basis of “starts with per term”, regardless of the filtering method.

Multi-input field - Default filtering, autocomplete in the input field is switched off

Copying and Pasting Data from a Spreadsheet or Text File

The multi-input field can handle paste actions containing multiple items, such as items that have been selected in a column of a spreadsheet or text file. The user simply selects a whole column in the spreadsheet, copies it, and then pastes it from the clipboard into the multi-input field. Each item is represented as a token. If a single value is copied and pasted into the field, it is shown as a text value, as further editing might be required before it is converted into a token.

Grouping

You can group the items items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

Multi-input with grouped suggestions

Multi-input with grouped tabular suggestions

Due to a technical limitation, the group headers are not visible when clicking on the n More text.

Group headers not shown when clicking on 'n More' items

Styles

The following images show how the states of the multi-input field are styled.

Unselected

Unselected with predefined placeholder

Unselected on hover

In focus

Selected items shown as tokens

Expanded multi-selection

Error

Warning

Success

Information

For details on the different states, see UI Element States.

For more information on semantic colors for value states, see How to Use Semantic Colors.

Guidelines

Give the control a width that is appropriate for the range of values that are going to be entered. Try to avoid setting a fixed width on this control. Instead, embed it in a proper layout (such as a form, simple form, or grid layout) and work with the layout data property.
Provide meaningful labels for all input fields. Do not use the placeholder as a replacement for the label. The placeholder should only provide an additional hint.
The multi-input field can currently contain tokens and one free text value. If you allow only validated values, display an error or warning when the user tries to leave the field to indicate that the value entered is invalid, or remove the value.
If users try to select an item that has been selected before, we recommend setting an error state and providing a meaningful message.

Multi-input - Error state for an item that has already been selected

You can use the layout options of the form to add the unit of measurement (UoM) after the multi-input control. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

Developer Hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

The multi-input field can be used in the grid table, analytical table and tree table as well, as condensed mode is already supported, both for desktop and mobile (tablets).

Multi-input field in the grid table in condensed mode

Properties

Since the multi-input field is derived from the input field, refer to the properties in the input field article.

Resources

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

Elements and Controls

Multi-Combo Box (guidelines)
Input (guidelines)
Combo Box (guidelines)
Select (guidelines)
Select Dialog (guidelines)
Value Help Dialog (guidelines)
Tokenizer (guidelines)

Implementation

Multi Input (SAPUI5 samples)
Multi Input (SAPUI5 API reference)

Multi-Combo Box

The multi-combo box control is commonly used to enable users to select one or more options from a predefined list. The control provides an editable input field to filter the list, and a dropdown arrow to open the list of available options. The select options in the list have checkboxes that permit multi-selection.

Usage

Use the multi-combo box if:

The user needs to select one or more options from a long list of options (maximum of approximately 200).
The values of the option list contain secondary information that does not need to be displayed right away.

Do not use the multi-combo box if:

The user needs to choose between two options, such as ON or OFF and YES or NO. In this case, consider using a switch control instead.
You need to display more than one attribute. In this case, consider using the select dialog or value help dialog instead.
The user needs to search on multiple attributes. In this case, consider using the select dialog or value help dialog instead.
Your use case requires all available options to be displayed right away, without any user interaction. In this case, consider using checkboxes instead.
You want to enable users to add custom values. In this case, consider using the multi-input field.
Your use case requires more options to choose from. In this case, consider using the multi-input field, either with the select dialog or value help dialog (for more than 1000 items).

Information

For more information on which selection control to choose, see the selection control overview.

Responsiveness

The multi-combo box is optimized for keyboard and mouse interaction.

Size S

Filter bar with multi-combo box - Size S

Option list in full screen - Size S

Size M

Filter bar with multi-combo box - Size M

Size L

Filter bar with multi-combo box - Size L

Also see the section on behavior for mobile devices.

Components

Input Field

The input field (2) can display a placeholder text (6) when it’s empty, or a token (1) if a value is selected.

Dropdown Trigger

The dropdown button (3) collapses and expands the dropdown list.

Option List

The option list (7) contains a list of selectable options (5). Clicking the label of an entry closes the option list and creates a token for the selected option. To enable multi-selection, every entry also has a checkbox (4). Clicking a checkbox creates a token. The option list remains open.

Components of the multi-combo box

Two-Column Layout

Use the multi-combo box with a two-column layout if you need to display additional information for the selection options, such as currencies, country abbreviations, or system abbreviations.

Multi-combo box with a two-column layout

Behavior and Interaction

Select a Value

There are three ways to select an item from the list:

Tick the checkbox (option list remains open).
Click the label of a select option (option list is closed).
Use the keyboard (spacebar or Enter).

The user clicks the input field to place the cursor in the field (1). Clicking the arrow displays the list (2). As the user types into the input field, the list is filtered accordingly (3). The up and down arrows move the focus within the list (4), while the typed text remains in the input field. Selected options are automatically entered into the input field as tokens (5).

If the user selects items from the filtered option list (3) by clicking the checkbox or by pressing the spacebar of the keyboard, the text entered in input field remains. The option list stays open. If the user selects items by clicking the label or by pressing Enter, the entered text is cleared and the option list is closed.

Developer Hint

With the showitems API, you can open the option list without having the dropdown arrow in a pressed state. Clicking the arrow again opens the full option list and sets it to pressed state. This way, you can show some items on focus and all items on click.

Input Field

Any character in the input field acts as a filter for the option list. The input field only allows users to type text that matches the items in the list. If the user tries to enter character combinations that are not in the option list, visual feedback is provided to indicate that the combination of characters is invalid, while the input field suppresses the characters entered.

Behavior - Sizes M and L

Choose from Option List

The option list displays all the available items that the user can choose from. Clicking the arrow opens the option list below the field. If there is not enough space to display the dropdown list below the field, it is displayed above the field instead.

Reviewing Tokens

If tokens have been selected, and the multi-combo box is not in focus, the input field displays as many tokens as possible in the available space. If more tokens have been selected, an [n] More label indicates the number of hidden tokens. The tokens in the input field appear in the order in which they were selected.

Clicking the [n] More label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its checkbox or label.

Multi-combo box - 'n More' label

If the length of the last selected token exceeds the width of the input field, a label [n] Item/s is shown when the field is not in focus.

Clicking the [n] Item/s label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its checkbox or label.

If there is only one token in the input field and its length exceeds the width of the input field, the text is truncated. Clicking the token opens a popover below the input field, in which the full text of the token is shown.

Multi-combo box - '1 Item' case (desktop)

Multi-combo box - 'n Items' label (Desktop)

Filtering the Option List

When the user starts typing in the input field, the option list is filtered. Only items that match the characters entered are shown in the dropdown list. The default filtering method is “starts with per term”, which matches the beginning of each word in an item’s text.

In addition, application developers can set a custom filtering method “starts with” or “contains” (method: setFilterFunction). The “starts with” approach filters only for items where the beginning of the label matches the query entered. The “Contains” approach searches the full label for a match.

As a visual hint for the user, the matched characters are highlighted in the option list items. The highlighting works on the basis of “starts with per term”, regardless of the filtering method.

If the filtered option list contains items that start with the characters entered by the user, the first matching, unselected item is auto-completed in the input field.

Warning

The typeahead input feature is not available for Android devices.

Multi-combo box - Default filtering and auto-complete

Grouping

Option list items can be grouped. Visually, the group header is a separate line above the items it groups. It does not currently provide an interaction of its own.

Multi-combo box - Grouping (desktop)

Multi-combo box - Grouping (mobile, Size S)

Behavior for Mobile Devices

The following sections describe how the multi-combo box interacts on mobile devices.

Clicking the Arrow

Clicking the arrow opens the option list in a full screen dialog (1) with a title displayed in the header (2). The Close button (3) closes the dialog and cancels any selection changes in the option list. Clicking the label of an entry (4) closes the option list and creates a token of the selected option. By selecting a checkbox (5), the option list remains open and allows multi-selection. The OK button (6) takes over the selection and closes the dialog.

Left: Filter bar with multi-combo box; Right: Full screen multi-combo box selection

Developer Hint

The title of the full-screen dialog could be customized by adding a label as ariaLabelledBy to the multi-combo box. If no label is associated with the multi-combo box, the default title “Select” is set.

As the user types into the input field (7), the list is filtered using the default “starts with per term” approach. Pressing the button next to the input field (8) toggles the view between all options and the selected options only.

Left: Option list, filtered by user input; Right: Selected options from the list

Input Field on Collapsed List

If items have already been selected, the input field remains functional and the tokens remain visible (1). Clicking the Remove icon in a token removes it (2). When the user clicks the input field, the list opens in full screen (3). Clicking the input field sets the focus on it (4) and the mobile device keyboard opens (5). When the user starts typing, the list is filtered (6) using the “starts with per term” approach. The input field only lets the user type characters that match the items in the list.

Left: Multi-combo box with token in the input field; Right: List for selection filtered by a character

Multiple Selected Items

Not all the selected tokens can be displayed at the same time because the space is limited to the size of the input field (6). Swiping to the side scrolls horizontally to reveal a cropped token (7).

Swiping to display tokens

Copying and Pasting Data from a Spreadsheet or Text File

The control for the multi-combo box can handle paste actions containing, for example, multiple items that have been selected in a column of a spreadsheet or text file. The user simply selects an entire column in the spreadsheet and copies it. When items are entered into the multi-combo box, the user just pastes them from the clipboard and each item is then represented as a token. Only items that are part of the list are displayed as tokens.

Information

For information on how to manage leading and trailing whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Styles

The following images show how the states of the multi-combo box are styled.

Unselected

Unselected with predefined placeholder

Unselected on hover

On focus

Expanded

Hover highlighting in list

Expanded selection

Expanded multi-selection

Selected items shown as tokens

Error

Warning

Success

Information

For more information on how to use the different semantic states of the control, see How to Use Semantic Colors.

Guidelines

Label

The multi-combo box control can be displayed with or without a label. If the field is attached to another field, you don’t need to define a second label. For more information about labels in SAP Fiori, see the label guidelines.

Placeholder

Don’t use the placeholder attribute as an alternative to a label. This is important because the placeholder text will be overwritten as soon as the form is filled out. Labels are necessary because they indicate the meaning of the form fields if the placeholders are no longer visible. Show a placeholder only if the user needs a hint about what data to enter. Don’t repeat the content of the label. A hint could be a sample value or a brief description of the expected format. For more information about how to use the placeholder, see input field.

Option List

Keep the label of an entry in the select option list as short as possible because the list uses single lines only. Values that are too long may be truncated. If you need to indicate that none of the selection options are selected, show a blank input field. Define a default selection whenever possible. The multi-combo box cannot display columns. If you want to show two values in the option list, show the leading information first, followed by the secondary information in parentheses, such as Walldorf (Germany).

Sorting

The option list contains all available items that the user can choose from. Choose one of the following styles depending on how you want the content to be arranged:

Logical: Sort items into a meaningful order. Group related options together and show the most common options first followed by less common options.

Logical multi-combo box

Alphabetical: Sort currencies, names, and so on into alphabetical order. We recommend this for lists with more than eight items.

Alphabetical multi-combo box

Numeric: Sort numeric values into a sequential order with the lowest number first.

Numeric multi-combo box

Chronological: Sort time-related information into chronological order with the most recent first (if applicable).

Chronological multi-combo box

Width

You can adjust the width of the option list to some extent. The multi-combo box control is usually used in forms, where the width is determined by the form element or container in which it is embedded. Therefore, we don’t recommend defining a fixed width, but rather working with proper layout containers such as the form, simple form, or responsive grid layout, and with the layout data property, where the width is defined. If you need to restrict the width to a defined value, set the width accordingly. Keep in mind that there’s no horizontal scrolling in the option list. Entries that are too long are truncated and users won’t be able to read them.

Information

If localized text isn’t an issue, such as with currency codes, use a smaller width.

Unit of Measurement

You can use the layout options of the form to add the unit of measurement (UoM) after the multi-combo box. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

Developer Hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

Multi-Combo Box in a Filter Scenario

The multi-combo box can serve as a filter. For example, if the multi-combo box is offered in a table toolbar, and is empty (no tokens selected), the table shows all items. If the user selects picks something in the multi-combo box, the table shows only the matching items.

In addition, users can select or deselect all items from the option list in the multi-combo box using the keyboard. This is done by focusing somewhere in the list and pressing Ctrl+A / Ctrl+Shift+A.

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)
Select (guidelines)
Input Field (guidelines)
Form (guidelines)
Radio Button (guidelines)
Checkbox (guidelines)
Toolbar (guidelines)
Switch (guidelines)

Implementation

- Multi-Combo Box (SAPUI5 samples)
- Multi-Combo Box (SAPUI5 API reference)

Color Palette

You can use the color palette to let users choose a color from a predefined set of colors. The colors are fixed and do not change with the theme.

Color palette

Usage

Use the color palette if:

The user needs to select one color from a predefined set of colors.
The color set contains between 2 and 15 predefined colors.
There is no need to offer additional colors.

Do not use the color palette if:

Users need to be able to select any color. Use the color picker or color picker popover instead.
Selecting a color from a predefined palette is the typical case, but users should still be able to define their own colors. Use the color palette popover instead.

Responsiveness

The color palette supports cozy and compact content densities.

Size S

Size M

Size L

Components

A link to select the default color (optional).

The color palette, consisting of 2 to 15 color buttons.

A link that opens a color picker in a dialog (optional).

Recent colors (optional). Users can see the last 5 colors they have recently picked. This function helps users to select colors that they have already chosen from the color picker. By default, this feature is visible.

Color palette with all optional features

Color palette with 15 colors and just one recent color

Behavior and Interaction

Users can select a color with the left mouse button, the tap gesture, or by pressing SPACE or ENTER on a keyboard. The selected color is not indicated in the control itself.

Hovering over a color provides a visual feedback.

To navigate between different colors on a keyboard, use the arrow keys.

Visual feedback on hover

Guidelines

Show the selected color in another place. The color palette does not visualize the selected color.
Label the color palette.
If you do not want to show the color palette in-place, consider the color palette popover instead.

Resources

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

Elements and Controls

Color Palette Popover (guidelines)
Color Picker (guidelines)
Color Picker Popover (guidelines)

Implementation

Color Palette (SAPUI5 samples)
Color Palette (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

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

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

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)
Team Calendar (SAPUI5 Sample)
Single Planning Calendar (API)
Planning Calendar (API)

Radio Button

Radio buttons provide users with a set of mutually exclusive options. They allow a user to select only one option from two or more choices. Each option is represented by a radio button. Consequently, radio buttons only work in groups.

Usage

Use the radio button if:

You need to help users choose quickly between at least two clearly different choices.

Do not use the radio button if:

You need to offer the user the option of multiple selection. In this case, use checkboxes instead because radio buttons are for single-selection contexts only.
You want to allow the user to select list items. Instead, let the user tab the list item to make a single selection (consider a message toast for confirmation) and provide checkboxes to select multiple list items.
The default option is recommended for most users in most situations. In this case, consider a dropdown list instead, which uses less space by not showing all options straightaway.
You need to present more than 8 options. Use a dropdown box or list view.
In special cases, there are only two mutually exclusive options. Combine them into a single checkbox or toggle switch. For example, use a checkbox for “I agree” (for example, to terms and conditions) instead of two radio buttons for “I agree” and “I don’t agree”.
The options are numbers with fixed steps. Use a slider control.

Responsiveness

The radio button group control is not responsive. A horizontal radio button group should be displayed as a vertical group on smartphones because a horizontal group should never break into two lines.

Also note that the control does not handle long labels in horizontal groups. Such labels do not break and are not truncated. Therefore, check label lengths and padding in horizontal groups on desktop and tablets.

A horizontal radio button group does not match the size of mobile phone screens

On smartphones, a horizontal group should always break into a vertical button group

Behavior and Interaction

Activation

The user taps a radio button to activate the related option. Note that tapping an activated option does not deactivate it, but tapping a different option transfers activation to that option. Therefore, a user can select only one option from a group of radio buttons.

A group of radio buttons behaves like a single control: Using the tab key sets the focus directly on the selected option. Users can cycle through the group using the arrow keys.

Styles

States

A radio button can have different states that affect its appearance:

Control states, such as “enabled” or “read only”
Value states, such as “error” or “warning”, which are indicated using semantic colors
Visual states, such as “regular” or “hover”
Additional states, such as “selected”

For details on the different states, see UI Element States.

For more information on semantic colors for value states, see How to Use Semantic Colors.

Radio button interaction states

Column Attribute

The radio button attributes also have a set arrangement so that you do not have to implement them for every single control. The column attribute adds or removes n-columns to a set of radio buttons.

Three columns – The example shows background color settings

One column – The example shows a customer survey

Guidelines

The radio button control serves the purpose of exclusive selection and adds clarity and weight to very important options in your app. Use radio buttons when the options being presented are important enough to occupy more screen space. They should only be used if the user needs to see all available options instantly and side by side. Radio buttons draw more attention to the options as they emphasize all options equally.

Labeling

A label to indicate the option is mandatory for each radio button. Limit the radio button’s label to a single line.

Sorting

List the options in a logical order, such as lowest to highest risk, simplest to most complex operation, or most to least likely to be selected.

Alphabetical ordering is less recommended as it is language-dependent and therefore not localizable.

Aligning

Try to align radio buttons vertically instead of horizontally, especially for long labels. Horizontal alignment is harder to read and localize. Consider horizontal alignment in cases of one-word labels, such as in the background color settings example above.

In forms, always align radio buttons vertically instead of horizontally as the length of the labels may vary for different languages.

Do not put two radio button groups right next to each other as it is difficult to determine which buttons belong to which group. Use group labels and padding to separate them.

Offering “No Choice”

If the user is also able to select none of the options, be sure to add this option to the control as well (as this option is generally not offered in the control). Add a radio button that offers None or Does not apply.

Default State

Because radio buttons do not generally offer “no choice”, the app should show the less risky option (most likely the first option in the group) as preselected by default.

Exceptional Case: No Preselection by Default

In rare cases, preselection might result in incorrect inputs or assumptions. One such example is gender selection in a form. In this case, you should offer no preselection and decide whether a user input is mandatory or not depending on the use case.

If a choice is mandatory, set an error state if validation proves that a user did not select an option.

Offer no selection by default in this case of gender selection because a preselection might be misleading

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)
Switch (guidelines)
Checkbox (guidelines)

Implementation

Radio Button (SAPUI5 samples)
Radio Button (SAPUI5 API reference)

Table Personalization Dialog

The table personalization dialog allows you to display and modify table settings. It is a UI pattern that defines column order and visibility.

Usage

Use the table personalization dialog if:

You have small tables.
You have a manageable number of columns.

Do not use the table personalization dialog if:

You have large tables.
You have a lot of columns to manage.

For larger tables you can use the P13n dialog (sap.m.P13nDialog) instead.

Responsiveness

On a desktop and tablet, the control appears as a dialog window.

The table personalization dialog should always be displayed in full screen mode on a smartphone device.

Table personalization dialog - Smartphone - Size S

Table personalization dialog - Tablet - Size M

Table personalization dialog - Desktop - Size L/XL

Layout

Position on the Screen

The dialog always opens in a modal window in the center of the screen.

For smartphones, stretch the dialog to fill the entire screen. For tablet and desktop devices, keep the modal window.

Layout of the Dialog

The table personalization dialog comprises the following five areas:

(1) Header

(2) Toolbar

(3) Subtoolbar

(4) Column list

(5) Footer toolbar

Table personalization dialog – Overview

Components

The table personalization dialog contains the following sections:

Header

The header displays the dialog title.

Table personalization dialog – Header

Toolbar

The toolbar displays the Move Column Up and Move Column Down buttons and the Search field.

Table personalization dialog – Toolbar

Subtoolbar

The subtoolbar displays the All checkbox for selecting all columns, and an Undo Personalization button.

Table personalization dialog – Subtoolbar

Column list

The column list displays the result list of columns. The user can use the search field in the toolbar to filter the selection.

Table personalization dialog – Column list

Footer toolbar

The footer toolbar displays an OK and a Cancel button.

Table personalization dialog – Footer toolbar

Behavior and Interaction

Open the Dialog

To open the table personalization dialog, the user must click the Personalize button on the right-hand side of the table toolbar.

Table personalization dialog – Table

Table personalization dialog – Open dialog

Show or Hide Columns

To show or hide columns, the user only needs to select or deselect the checkbox of a column (list item).

(1) Columns are visible in the table.

(2) Columns are hidden in the table.

Table personalization dialog – Show/Hide

The user can show or hide all columns with just one click. A checkbox on the left-hand side of the subtoolbar enables all list items to be selected or deselected.

(1) Columns are visible in the table.

(2) Columns are hidden in the table.

Table personalization dialog – Show all

Table personalization dialog – Hide all

Move Columns

Two buttons in the toolbar on the left-hand side enable a selected column to be moved up or down.

Table personalization dialog – Move buttons

Move Column Up

(1) Select a column (by clicking on the list item).

(2) Use the Move Column Up button to move the column to the left in the table.

If the first position has been reached, the Move Column Up button is disabled.

Table personalization dialog – Select

Table personalization dialog – Move Column Up

Move Column Down

(1) Select a column (by clicking on the list item).

(2) Use the Move Column Down button to move the column to the right in the table.

If the last position has been reached, the Move Column Down button is disabled.

Table personalization dialog – Select

Table personalization dialog – Move Column Down

Search/Filter Columns

A search field in the toolbar on the right-hand side enables columns to be searched/filtered.

Table personalization dialog – Search field

The user can type any character into the search field to filter the columns to match the input.

Table personalization dialog – Search column

To reset a search, the user must delete all the characters that have been entered, or simply presses the Cancel button in the search field.

All the columns are shown again in the list.

Table personalization dialog – Search reset

Undo Personalization

The Undo Personalization button in the subtoolbar on the right-hand side resets all settings to the initial state.

If the table personalization dialog is used together with variant management, the button resets the changes to the initial state of the selected variant.

Table personalization dialog – Undo

Confirm/Cancel Changes

The changes are adopted when the user closes the dialog via the OK button.

The Cancel button closes the dialog without adopting the changes.

Table personalization dialog – OK/Cancel

Guidelines

Search Behavior

The search is a live search (also known as “search-as-you-type”), which is triggered by each character the user enters or deletes. For more information, see search.

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

Toolbar (guidelines)
Button (guidelines)
Search (guidelines)
List (guidelines)
Footer Toolbar (guidelines)

Implementation

Table Personalization Dialog (SAPUI5 samples)
Table Personalization Controller (SAPUI5 samples)
Table Personalization Dialog (SAPUI5 API reference)
Table Personalization Controller (SAPUI5 API reference)

Range Slider

A range slider is a user interface control that enables the user to select a value range within a predefined numerical interval.

Range slider

Usage

Use the range slider if you want to select a value range within a predefined numerical interval. If you want to specify only a single value within a predefined numerical interval, use the slider instead.

Responsiveness

The range slider itself is not responsive. It adjusts to the responsiveness of its parent container by recalculating and resizing the width of the control. The range slider supports the cozy and compact form factors.

Types

Only a horizontal range slider is available.

Components

The range slider consists of:

Progress line
Minimum and maximum value
Grips
Tooltips or input fields

Range slider components

Behavior and Interaction

Changing Values

If the range slider is editable, the hand cursor appears when hovering over the range slider with the mouse. A tooltip also appears when hovering, displaying the current values of each grip. The grips move together with the corresponding tooltips.

The user can change the value range on the slider in two ways:

By using drag and drop to adjust the grips
By clicking the bar outside the value range. The corresponding grip then moves to the new position.

The grips can be moved with or without increments based on the predefined steps.

Range slider on hover

Range Slider with Input Fields

The range slider can be used with input fields instead of tooltips.

Range slider with input fields

Moving the Entire Range

Users can move the entire value range by dragging and dropping the progress line.

Range slider - Moving the entire range

Equal Values

The grips of the range slider can be positioned on the same value.

Range slider with equal values

Overlapping

The grips of the range slider can be moved across each other. The minimum can become the maximum, and vice versa.

Tick Marks

You can apply tick marks to the range slider. The tick marks are related to the step property. For example, if you have a range from 1 to 100 and a step of 10, the range slider will have 11 tick marks. The tick marks are responsive. If the distance between 2 tick marks is less than 8 px, all tick marks except for the first and last disappear.

Range slider with tick marks

Tick Marks and Labels

If tick marks are set, you can define labels for the tick marks. The labels are displayed below the tick marks and show the corresponding value of the tick mark. The labels must never overlap. You can also define labels only for specific tick marks if you don’t need a label for every tick mark on the slider. The application developer is responsible for defining a reasonable set of tick marks.

If there is not enough horizontal space to display all the labels, a responsive mechanism is activated. The first and the last label are always visible.

Range slider with tick marks and labels

Custom Values

You can define custom values as labels. This can be useful if your scenario requires descriptive intervals, such as as dates. Always keep the values as short and meaningful as possible.

Range slider with custom values as labels

Developer Hint

In order to use custom scales in a slider, you must map them to the floats for the slider scale.

Properties

The step property must be positive. If a negative number is provided, the default value 1 is used instead.
The minimum, maximum, and value properties can be decimals (float values). The slider automatically sets the minimum value to 0 and the maximum value to 100 by default.
The width of the control can be provided in percentage (%), em, px, and all possible CSS units. The slider automatically sets the width of the slider to 100% by default.
The range property determines the range in which the user can select values. If the value is lower/higher than the allowed minimum/maximum, a warning message is displayed.
The inputsAsTooltips property indicates whether input fields are being used as tooltips for the grips.

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

Slider (guidelines)
Input Field (guidelines)

Implementation

Range Slider (SAPUI5 samples)
Range Slider (SAPUI5 API reference)

Search

A search is a means of accessing information quickly. If an amount of data is too large for users to find something just by scanning through it, you should consider providing a search function.

Search field

Usage

Use a search field (sap.m.SearchField) if you want to enable users to enter text to search for information. The search field is also the control of choice for filtering down a given amount of information.

Responsiveness

When suggestions are turned on, the suggestion list displays differently depending on the device type.

Size S (Smart Phones)

Clicking the search field opens a new full screen dialog in which items can be selected from a list of suggestions.

Size S

Size M (Tablets)

Suggestions are shown below the search field.

Size M

Size L (Desktops)

Suggestions are shown below the search field.

Size L

Types

SAP Fiori comes with two different search types.

The manual search is triggered explicitly after the user enters text in the search field and clicks the Search button or presses the Enter key.
The live search (also known as “incremental search” or “search-as-you-type”) is triggered by each character that the user enters or deletes. There is a default delay of 400 ms before sending the search data to the back end. This ensures better performance and optimizes user experience.

Queries that are entered are used to search the back-end data for term matches (not case-sensitive). While a live search uses a “contains” approach, a manual search uses a “starts with” approach. “Contains” means that the result needs to match the query only partly to be a valid result. “Starts with” means that full terms of the result need to start with the entered query to be visualized.

Layout

The search input field (or search box) consists of two parts:

The text input, which is left-aligned. Initially, the field shows a placeholder (Search). As soon as the user enters a character, this prompt text disappears. It appears again if the user deletes the entry.
If a manual search is to be implemented, a search button with a magnifier icon is placed on the right side of this input control. The user clicks this button to trigger the search. In live searches, the magnifier icon is also placed here, but it functions more like an additional indicator to signify that this is a search input field. It also functions as an explicit search button if the user wants to search again for a query that has already been entered.

All item attributes defined by the app development team are searched. When the results are displayed, the items found do not necessarily have to show the attribute through which the item was found. The results are displayed in the same list that contained the original item set. Initial grouping and the order of the list are not affected by the search.

When the split screen is used, the search field appears at the top of the master list. In full screen mode, the search field is placed at the top of the page.

Behavior and Interaction

Entering a Search Term

Search terms can be entered easily into the input field. The search box then displays all full-text search terms. There is no line break and no truncation if the query is longer than the input field. Results might also be displayed that do not match the query in their title or subtitle. This might be because details can also be searched for. The user can see the matching terms in the specific details section.

Deleting a Search Term

The user can click the “X” icon ( ) button to remove the text from the field. In the case of the live search, this also resets the search. In a manual search, deleting the search term and then triggering the search resets the search results.

Refreshing

If the Refresh button is available, the user can update the list without triggering a new search. This is usually needed when backend data changes quickly and often.

If the currently selected item is no longer available after the list has been refreshed, the next item in the line is selected. If no next item is available, the first item in the line should be selected next.

Search field with refresh

On touch devices, the Refresh icon is not visible in the search field. In this case, Pull Down to Refresh is used instead. The Pull Down to Refresh arrow icon is animated and spins to signal that the user should release it.

Pull to Refresh

Information

For information on how to manage leading and trailing white space (blanks) when copying and pasting text into input controls, please see removing leading and trailing white space.

Properties

The following methods are important.

For the live search:

attachLiveChange(oData?, fnFunction, oListener?) Attach event handler fnFunction to the liveChange event of this sap.m.SearchField.
detachLiveChange(fnFunction, oListener) Detach event handler fnFunction from the liveChange event of this sap.m.SearchField.
fireLiveChange(mArguments?) Fire liveChange event to attached listeners.

For the manual search:

attachSearch(oData?, fnFunction, oListener?) Attach event handler fnFunction to the search event of this sap.m.SearchField.
detachSearch(fnFunction, oListener) Detach event handler fnFunction from the search event of this sap.m.SearchField.
fireSearch(mArguments?) Fire search event to attached listeners.

If a Refresh button is needed:

getShowRefreshButton() Getter for property showRefreshButton.
setShowRefreshButton(bShowRefreshButton) Setter for property showRefreshButton.

To show the Search button:

getShowSearchButton() Getter for property showSearchButton.
setShowSearchButton(bShowSearchButton) Setter for property showSearchButton.

To ensure the focus is set to input:

setSelectOnFocus(bSelectOnFocus) Setter for property selectOnFocus.

If the search is triggered automatically when the value of the field is changed (unlike the liveChange event, the change event is not fired for each key press):

attachChange(oData?, fnFunction, oListener?) Attach event handler fnFunction to the change event of this sap.m.SearchField.
detachChange(fnFunction, oListener) Detach event handler fnFunction from the change event of this sap.m.SearchField.
fireChange(mArguments?) Fire change event to attached listeners.

Guidelines

Implement the live search whenever possible.
Use a manual search only if the amount of data is too large and if your app would otherwise run into performance issues.
Show an appropriate prompt text:Search if queries are sent to all connected services, or Search In: if the search is limited to a certain source or providing service.

Resources

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

Elements and Controls

Input Field (guidelines)
Button (guidelines)
Master List (guidelines)
Split Screen (guidelines)
Full Screen (guidelines)
Enterprise Search (guidelines)
Cozy/Compact (guidelines)

Implementation

Search Field (SAPUI5 samples)
Search Field (SAPUI5 API reference)

Feed and Notes

Feeds and notes are commonplace in many SAP Fiori applications. The sap.m.FeedInput control allows users to input and post plain text, while the sap.m.FeedListItem control handles and displays this text. Both can be used individually, but they also complement each other well to create a simple feed or notes control.

Usage

Feed Input

Use the feed input if:

A user needs to input small amounts of text without formatting.
You expect multiple instances, such as notes or feed entries.

Do not use the feed input if:

The user needs to format the text (rich text editor).
You need only a single text box instance. In this case, use the text area (for multiple lines) or the text control (for a single line).

Combination of Both Controls (as Feed or Notes Control)

Use both controls if:

You need a feed to show textual posts.
Your users need to input notes.

Do not use both controls if:

You expect extensive social interaction in the feed.
Users need to reply at item level instead of creating a new post.
You want to display SAP Jam feeds.

In these cases, use the social timeline instead (requires SAP Jam).

Responsiveness

Due to their responsive behavior, both controls can be used in small and large view ports or screens.

For better usability, we highly recommend that you do not stretch the controls across the full width on large screens – 2/3 or even 1/2 works just fine. This can easily be achieved using the grid layout .

Feed – Size S

Feed – Size M

Feed – Size L

When the width of the available space falls below 25 rem (for example, in portrait mode on smartphones), the two controls respond as follows:

If a user image previously appeared in the feed input, it will be omitted in narrow screens to give the text field more space.
If there is no user image, there will be no visual change.

Feed input – Responsiveness

In the feed list item, the user’s name, image, and the time stamp move on top of the text. If there is no image, the name and time stamp are left-aligned together with the text.

Feed list item – Responsiveness – With image

Feed list item – Responsiveness – Without image

Layout

Feed Input

The feed input consists of:

A text input field with a placeholder (input prompt)
Example: Add a comment
A Send button
An optional user image

You can also choose not to show user images at all. In this case, the size of the input area increases automatically.

Feed input – Layout – With user image

Feed input – Layout – With generic user image

Feed input – Layout – Without user image

Feed List Item

The feed list item consists of the user’s name and an optional picture of the user who wrote the note or update. The name can contain a link that triggers a quick overview of the user’s profile data. The actual text written by the user follows the name. Below it is a separate byline that can contain a time stamp and an attribute in the form of free text. This allows you to put in your own attribute, such as Approval, Internal, or External. Both the time stamp and the attribute are optional.

If the name is a link, the picture should also be linked with the same attributes.

Feed list item – With user image and linked name

If the user does not have a picture assigned, a placeholder is shown instead:

Feed list item – With generic user image and linked name

The name (and picture) can also be read-only, that is, without a link:

Feed list item – With user image but without links

If the app does not support user images, they can be omitted:

Feed list item – Without user image but with linked name

Here, too, the name can be read-only:

Feed list item – Without user image and read-only name

It’s also possible to display rich text (formatted text) in the feed list item. This feature should be handled with care as it allows for countless custom layouts.

Please see that you use it responsibly and provide your users with a consistent experience. Only deviate from the default layout and font if absolutely required by the use case.

Example use case: Render URLs as links.

Feed list item – Layout – Rich text

Information

The items in the feed list must be homogeneous. This means that they must contain the same layout and visualization. For example, it is not possible to have a feed containing both linked and plain names, or both user images and default images.

Special Case: Multiple Types of Notes

Apps sometimes need to discern between different types of notes. There is an easy way to allow users to choose which type they want to see or add to the list.

You can place a toolbar containing a select control at the top of the feed input control. From there, users can select the type of notes, such as Internal Notes or External Notes. The list of notes must contain only the type selected. If the user adds a note via the feed input, the type must be set automatically according to the selection.

Interaction – Note types (1)

Interaction – Note types (2)

Interaction – Note types (3)

Components

The feed input and feed list item do not contain subcontrols. However, you can easily combine them to create a simple feed or notes control.

Although the feed input counts as a single control, the input area inherits its behavior from the sap.m.TextArea control.

Behavior and Interaction

Send Message

Initially, the feeder contains a placeholder (input prompt), and the Send button is disabled, with reduced opacity.

Clicking into the input field puts the focus on the field and allows to start typing.

When the user starts to type, the placeholder disappears and the Send button becomes active and more prominent.

If the available width is below 25 rem (for example, in portrait mode on a smartphone), the picture is removed.

To send the text, the user must explicitly click the Send button. Pressing Enter on the keyboard (on-screen or physical) results in a line break.

Feed input – Behavior

Show More Text

When the text exceeds a certain number of characters (you can overwrite the default value), the rest of the text is truncated and a MORE link appears after the truncated section.

Initially, the MORE link is gray, so it does not divert the user’s attention away from the actual text. When the user moves the mouse over the feed text, the MORE link is highlighted. Hovering over the link underlines it.

Show Less Text

When the user expands the text, the name of this link changes to LESS, but still behaves the same way as before.

Feed and Notes in Tables

In tables, users sometimes need to see if an object has a comment (or feed or note) without further navigation, and even be able to add/edit right from the table.

Add an additional row, named according to the type of user input, such as Comment, Note, or Feed.

Place a link inside each cell with the appropriate action (row: Comment, link: Comment/ row: Feed, link: Post).
If there can be more than one item, add a counter after the text as well (see example on the right).

This solution works with every table control.

Feed and notes in tables (1)

Optional:
Depending on the use case, it might help users if they can see the latest note. The responsive table allows the feed list item (sap.m.FeedListItem) to be used inside a cell.

Reduce the property “maxCharacters” to an amount that your table can handle.
Note that once the maximum number of characters has been reached, a MORE link allows users to expand the text. Technically, this is no problem for the responsive table, but you need to ensure that the layout of your page allows this kind of expansion.

Place a link below the feed list item to allow users to add something (as described above).

Feed and notes in tables (2)

When the user clicks a link, such as Comment or Note, display a dialog showing all comments (notes, feed entries, and so on) along with possible actions, such as Add or Edit, depending on your use case.

There are several ways to show notes (comments, feed entries, and so on) in a dialog:

You can use the feed list item (and feed input) as described in this article.
If only one single note is allowed, you can use the text area.
For a large feed, you can use the timeline control (SAP Jam is required for social features).

Actions On Feed List Items

Applications can define actions that users can perform on individual feed posts. The two most typical actions are Edit and Delete. Other actions can be introduced as required by the use case. To keep the feed as lightweight as possible, don’t overwhelm users with too many actions or complicated actions (max. 5 per post).

Interaction - Actions

Styles

By default, feed entries are separated by divider lines. We recommend that these separators remain enabled, since they help distinguish between individual posts. However, if your list is expected to hold only a handful of entries, you can disable the separators by setting the showSeparators property at list level (not at list item level) to none.

Guidelines

Because the feed list item is built on the basis of the standard list item, it inherits multiple properties that may not make sense in a feed use case.

Use only properties that are described in this article. Especially making the entire feed list item clickable can lead to functional issues and usability problems.

Don’t stretch the feed input or the feed list items across large screens (size L and beyond). This will have a negative effect on usability and readability. Instead, only use 1/3 or even 1/2 of the screen. Implement this with the grid layout .

If you display formatted text (rich text) in the feed list item, use formatting that is beneficial to users, not decorative formatting. Use formatting responsibly, and provide your users with a consistent experience. Deviate from the default layout and font only if absolutely required by the use case (example: render URLs as links).

Resources

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

Elements and Controls

No links.

Implementation

Feed Input (SAPUI5 samples)
Feed List Item (SAPUI5 samples)
Feed (SAPUI5 samples)
Feed Input (SAPUI5 API reference)
Feed List Item (SAPUI5 API reference)

Upload Collection

Information

The Remove/Close icons shown in this article do not yet reflect the new Remove/Close icon defined in the product standard for UX consistency. We will update this article as soon as the new icon is available in the corresponding controls.

Information

The upload collection replaces the deprecated sap.ca.ui.FileUpload control. Please refrain from using the old CA control.

Intro

The upload collection control allows users to upload single or multiple files from a device (desktop, tablet, or phone) to the SAP Fiori app. Typically, uploaded files appear in an Attachments tab. However, files can also be displayed elsewhere.

Usage

Use the upload collection control if:

You want to show a list of uploaded files that can be modified.
You want to allow users to add or remove files, and to change the file names.
You are still using the old sap.ca.ui.FileUpload control.

Do not use the upload collection control if:

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

Responsiveness

The upload collection control supports small, medium, and large containers.

Upload collection – Size S

Upload collection – Size L

Layout

The toolbar at the top of the upload collection control contains an Attachments header with a counter on the left, and an Add button for adding new items on the right. You can overwrite both the default text Attachments and the counter (property: numberOfAttachmentsText).

Files are listed vertically. Each item has a Rename () and a Remove () button.

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

Layout – Items

Attributes and Statuses

You can display additional attributes and statuses below the file name. Attributes can include the name of the person who uploaded the file, the upload date, the version number, file size, and so on.

App developers can also set individual statuses. These statuses usually refer to an object’s state in a workflow (such as Approved or Overdue).

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

Layout – Attributes and statuses

Technical Statuses

In contrast to the statuses mentioned above, technical statuses are not bound to a workflow or business process. Their main use is to show the current editing status of an object (Draft, Locked, Unsaved Changes). For further uses and more details see the object display components and draft handling articles.

Layout – Technical statuses

Types

The upload collection control offers two different modes: UploadCollection and UploadCollectionForPendingUpload.

The classic upload collection allows users to upload single or multiple files directly to the app, where these files are displayed as a list.

In contrast, the upload collection for pending upload requires the user to first add multiple files to a list (usually presented in a dialog) and then explicitly trigger the upload for the entire list.

When the dialog with the list is confirmed, the user returns to the app screen with the upload collection set to busy until the upload is finished.

Behavior and Interaction

Uploading Files

If empty, the upload collection provides users with a hint that they can use the Add button or drag and drop to upload files. This hint already provides a large enough zone for users to drop their files.

Developer Hint

Applications should not use self-built placeholder items to tell users that there are no files to display, since they would override this hint.

Interaction – Upload collection empty

Using the Add Button

The Add button triggers a native operating system dialog that allows users to select the files they want to upload. You can decide whether the dialogs should allow users to select multiple items, or only one item.

Interaction – Add

Once the files have been selected and the dialog closes, the uploading progress is shown in the list.

Users can cancel individual uploads by pressing the Remove button provided on each item.

Interaction – Upload in progress

Depending on the use case, the Add button can be either disabled or hidden.
If a user cannot upload any files at all, the button should be hidden completely.
If a user is only temporarily unable to upload files (for example, due to the server connection), the button should only be disabled to indicate that this state is temporary.

Using Drag and Drop

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

As soon as users start to drag a file over the application, the hint changes into a drop zone informing users where to place the file.

Interaction – Drag and drop - Start

When the file is over the drop zone, it changes again to tell users that they can release the file.

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

Interaction – Drag and drop - Before drop

Opening Files

The user can click the icons or thumbnails in front of the attachment. Opening files is handled differently depending on the operating system.

On a desktop device, clicking the file name or icon of a file opens the respective program that has been assigned to this file type. Mobile devices usually open a dialog in which the user can select an app that supports this file type.

Renaming Files

The rename function works identically on desktop and mobile devices.

The user clicks the Rename ( ) button.

The file name becomes an input field in which the existing name is highlighted. At the same time, the Rename ( ) and Remove ( ) buttons are replaced by two options: 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.

There are three ways in which to validate the new file name:

The user clicks somewhere outside the input field to change the focus.
The user clicks Rename.
The user presses ENTER.

Editing Files

If users need to edit more than just the name of uploaded files, applications can implement an edit dialog with all the elements that can be changed by the user.

The image shows an example of how to structure such a dialog. The fields depend entirely on the use case and can be freely determined by each application.

Important: Make sure that you trigger this dialog via the standard Edit button that is provided for each item.

Further details about editing parts of an object in a dialog can be found in the article manage objects – parts of an object. If multiple files need to be edited simultaneously, make sure to follow the guidelines for mass editing.

Interaction – Example of an edit dialog

Deleting Files

The delete function works identically on desktop and mobile devices.

As soon as the user clicks the Remove button on a file, a dialog appears asking the user to confirm the deletion of the respective file.

The file name has to be specified in the dialog. 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.

Interaction – 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. Use a quick view to show this additional information.

Examples:

Uploaded By: John Miller

Last Edited By: Donna Moore

Version 1.1

Do not use more than two or three linked attributes per item. Excessive use of clickable attributes will overload the UI with interactive elements and have a negative impact on usability.

Sorting and Filtering

Applications can enable sorting and filtering by placing the respective buttons next to the Add button. If both functions are provided separately, place Sort ( ) first, followed by Filter ( ). Each button should trigger the respective popover or dialog.

It is also possible to use the view settings dialog to handle both sorting and filtering in the same step. If you do this, use a combined button named Sort and Filter.

Interaction – Sort and Filter (1)

If a Filter is Set

Keep in mind to show the infobar if a filter is set. The sorting criteria should not be displayed in the infobar.

Clicking the infobar should bring up…
…the filter dialog if sorting and filtering are provided via separate buttons.
…the view settings dialog if only one Sort and Filter button is used.

Optionally, a button can be provided on the right hand side of the infobar to remove all filters.

Interaction – Sort and Filter (2)

Custom and Bulk Actions

App developers can introduce their own actions and apply an action to multiple objects (bulk actions).

Place both custom and bulk actions in the toolbar of the upload collection control. For the order of the actions, apply the same rules as for other toolbars.

If you want to use custom or bulk actions, you must use multiple selection (property: mode = MultiSelect). This mode removes the actions from each item. Instead, offer all necessary actions in the toolbar.

Interaction – Multi selection

Uploading a New Version

With SAPUI5 version 1.38 and higher, the old version of an upload collection will be automatically replaced when the user uploads a newer version. This change no longer requires the user to delete the old version manually.

To upload a new version, the user needs to select a file and click Upload New Version. This button needs to be provided by the application as a custom action (see previous section). The following dialog (identical to standard uploading procedure) allows the user to pick a new file to replace the old one.

Developer Hint

The parameter UploadCollectionItem can be used to update a file with a newer version. The old version will be removed from the list automatically while the new version is uploaded. For more information, visit UI5 Explored.

Handling Duplicates

Some applications may allow duplicate files and file names. This section covers steps to prevent duplicates.

Duplicate File Name During Renaming

In this example, there are two different image files: Product Picture Front and Product Picture Back.

The user types in a name that is identical to one that already exists.

When the user clicks Rename or tries to remove the focus from the input field, the field is highlighted (semantic color: error).

Placing the focus back on the field shows the error message (form field validation).

Duplicate Files During Upload

Information

Duplicate files are not recognized by the upload control. If needed, this feature must be implemented manually.

If a duplicate is recognized during the upload process, a dialog appears that allows the user to do one of the following:

1) This text explains the current conflict (no actions possible).

2) With Upload and replace, the current file is replaced with the newly updated one.

3) With Upload and rename automatically, the current file is kept and an incrementally increasing number is added to the newly uploaded file, such as “Technical Specs_2”.

4) With Skip this file, the file is not uploaded and the current file is kept instead.

5) If Do this for all n conflicts is checked, the selected action is applied to all remaining conflicts.

6) The OK button confirms selected action(s).

7) The Close button cancels the entire upload process.

Interaction – Upload duplicate – Details

Folder Structure

The upload collection control can display hierarchical folder structures containing files, similar to an operation system’s file browser or popular cloud storage services.

Info: Renaming and deleting folders works the same way as it does with files and will therefore not be covered in this section. For more details, check the respective sections on renaming and deleting files.

While files are represented by individual icons that correspond to the file’s MIME type, all folders are represented by the same icon ( ) since their contents may vary.

Instead of the regular title, use breadcrumbs to enable users to see which hierarchy level they are on, and to provide an easy way to navigate back to any previous step.

In the item counter after the breadcrumb, show the sum of all items in the current folder, counting both folders and files.

Folder Structure (1)

When the user clicks a folder, the current list is replaced by the contents of that folder. Note that the breadcrumb needs to be updated to show the previous folder as well as both the name of the current folder and number of items it contains.

Folder Structure (2)

The same behavior repeats as the user navigates deeper: the previous folder name is converted to a link, while the current folder is appended to the breadcrumb and both the counter and the list are updated.

Folder Structure (3)

If users are allowed to create their own folders, provide a custom action button in the toolbar called New Folder. With this button, trigger a dialog prompting users to enter a name for the new folder.

After confirmation, the new folder is created on the same hierarchy level that is currently visible in the upload list.

Folder structure – Dialog for creating a folder

Styles

The showSeparators property allows you to display dividers between each item. The default value is All, meaning that all dividers are shown. We recommend that you only turn off the separators if you expect to have just a few items. The separators make it easier for users to scan long lists.

Styles – Separators (default)

Styles – No separators

Guidelines

When to Show/Deactivate/Hide Actions

Apps can control the visibility and the active state for all actions at item level. This applies to the Edit and Delete buttons.

The properties are as follows:

VisibleEdit
VisibleDelete
EnableEdit
EnableDelete

All the properties are set to true by default.

If users are not allowed to edit uploaded files, all the Edit buttons should be set to invisible. The same applies to the Delete function.

Identical actions should be placed directly beneath one another.

Do not leave buttons enabled, only to show an error message informing the user that the function is not available.

Identical actions should always appear beneath one another.

Do

Show identical actions beneath each other

If users are not allowed to use a certain function, these buttons should not be shown at all.

Do

Hide functions if the user doesn't have authorization

If certain actions are unavailable in some cases, such as for files from other users, we recommended that you disable these actions.

Do

Disable functions not available for a specific file

Do not disable all actions. If users are not allowed to use a certain action, these buttons should not be shown at all.

Don't

Don't disable all actions

Identical actions should be placed directly beneath one another. In the example opposite, the Remove buttons on the lower two items should be visible but disabled.

Don't

Do not position the same actions differently

Placeholder Items

Applications should not use self-built placeholder items to tell users if there are no files to display. This information is provided automatically by the control.

Developer Hint

If you want users to be able to upload only specific file types, we recommend doing this via mime types.
You should also inform users on the UI about the file types they are allowed to upload.

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

Dialog (guidelines)
Object Display Components (guidelines)

Implementation

Upload Collection (SAPUI5 samples)
Upload Collection For Pending Upload (SAPUI5 samples)
Upload Collection (SAPUI5 API reference)
Upload Collection For Pending Upload (SAPUI5 API reference)

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

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

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.

4. Navigation

The navigation area contains back and forward arrows, the Today button, a date interval link, and the time strip. Clicking the Today button takes the user to the period containing the current day. Clicking the date opens a date picker for direct navigation.

5. Time strip for hours/days/months

The time strip reflects the selected view, and shows the hours, days or months that are currently visible. In all views that show days (Days, 1 Week, 1 Month), you can display calendar weeks in an additional line below the time strip (property: showWeekNumbers).

6. Row header

The row header identifies the object for which the appointments are shown. It pops in if there is not enough space. The row header can contain a picture or icon, a title, and a subtitle.

You can also add an action on the row header (event: rowHeaderClick).

7. Row

The row contains all appointments for an object. You can turn the alternating row coloring on or off. By default, the alternating rows option is turned on.

8. List item

The list item contains the row header, row, appointments, and interval appointments. Each row can show different working and non-working days.

If the users have a specific working schedule, the non-working days can be different on each row. This can be applied not only for weekends, but also for non-working days based on specific schedule differences.

9. Interval appointment

Each row can also have interval appointments, which differ from half-sized appointments visually and in that they are always at the top of the row. Interval appointments can be used to show appointments that last for a longer period of time, such as vacations or workshops.

You can opt to hide the space reserved for interval appointments if no such appointments exist for that time period.

10. Appointment

Appointments consist of an icon or picture, a title, and a subtitle. Concurrent appointments are shown one above the other. There are two appointment sizes – regular and half size. Half-sized appointments save space, but don’t show a second line with appointment details.

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