Upload Set

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

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

When to Use

Use the upload set control if:

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

Do not use the upload set control if:

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

Components

  1. Toolbar with upload and download controls
  2. Edit and delete actions
  3. Technical status
  4. Attributes and statuses

Toolbar

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

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

List

Actions (2)

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

Technical statuses (3)

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

Attributes and statuses (4)

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

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

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

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

Behavior and Interaction

Uploading Files

The upload set offers two basic working modes:

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

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

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

Developer Hint

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

Empty State

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

Interaction - No items
Interaction - No items

Drag and Drop

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

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

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

Interaction - Drag and drop
Interaction - Drag and drop

Opening Files

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

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

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

Renaming Files

The Edit function works identically on desktop and mobile devices.

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

Deleting Files

The Delete function works identically on desktop and mobile devices.

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

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

Clickable Attributes

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

Examples:

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

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

Responsiveness

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

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

Example

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

Upload set in object page
Upload set in object page

Other possible scenarios:

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

Top Tips

When to Show, Disable, and Hide Actions

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

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

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

Related Links

Elements and Controls

Implementation

Date Range Picker

The date range picker allows users to enter a date range by either typing two dates in the input field or selecting a date range in the calendar.

The date range picker can also be used to enter a single date.


Basic date range picker – live example

When to Use

Do

Use the date range picker if:

  • Users need to enter a date range and you know that the keyboard is not the primary device used for navigating the app.
Don't

Don’t use the date range picker if:

  • Users need to enter a date and a time. In this case, use the date picker or time picker instead.
  • Selecting ranges is not the user’s primary goal. In this case, use the simple date picker.
  • If the keyboard is the primary device used for navigating the app, use two inputs. This allows the user to jump quickly from field to field.

Anatomy

  1. Date input field: Field for typing in dates directly. It contains a mask.
  2. Text: A placeholder or the selected/typed text.
  3. Date range picker button: Button that opens the calendar.
  4. Calendar: See the calendar guideline for more details.
  5. Current date
  6. Selected date range
Anatomy of the date range picker
Anatomy of the date range picker

Variants

Restricted Date Range

You can set minimum and maximum dates. In this case, the user can only select dates within the approved range.

Predefined Date Range

You can set a predefined date range that is selected by default when the user opens the calendar. The user can still change the dates.

Date Display in the Input Field

You can specify the format of the dates in the input field. Supported formats are based on the Unicode Locale Data Markup Language (LDML) date format notation.

You can also specify the symbol that separates the start and end dates.



Minimum/maximum dates, specific date format – live example
Predefined date range, custom delimiter – live example

Behavior and Interaction

Selection

Date range: After selecting a start date, hovering over another date turns the dates in between to light blue, indicating that they are in the selected range. When the user selects an end date, the calendar closes and the range appears in the date input field.

Single date: To enter a single date, the user can type one date into the input field, or select the same day as the start and end date in the calendar.

Shortcuts

The following shortcuts are available for entering specific dates:

  • “today”
  • “yesterday”
  • “in x days”
  • “x days ago”
  • “yesterday – today”
  • “x days ago – in x days”

Restricted Date Range

If minimum and maximum dates have been set, selection and navigation to dates outside this range is disabled.

Formatting

If the user types the date in the input field, it must fit the required date format. For example, if the format pattern is “yyyy-MM-dd”, a valid user input would be “2023-07-30”.

Related Links

Implementation

Text Area

The text area is an input component that allows the user to enter several lines of text.

Basic text area – live example

When to Use

Do

Use the text area:

  • If users need to enter more than one line of text.
Don't

Don’t use the text area:

  • If you only want users to enter a single line of text. Use the input component instead.

Anatomy

  1. Input field: Container in which a user enters text.
  2. Text: Placeholder or typed text. The placeholder is an optional prompt text that is displayed when the input field is empty.
  3. Scrollbar
  4. Counter: If you have set a character limit without restricting text input, the counter indicates how many characters are left, or how many characters exceed the limit.
Anatomy of the text area
Anatomy of the text area

Variants

Text Area with Character Limit

You can set a character limit for the text. In this case, you have two options for handling the text input:

Text is cut off after the character limit

Once the character limit has been reached, users can no longer type or enter additional text. Pasted text is cut off. This is the default setting.

No text entry after 20-character limit is reached – live example

Text can exceed the character limit

You can allow the user to enter text that exceeds the character limit. We strongly recommend using this variant because it offers users much better orientation:

  • A character counter indicates how many characters are can still be entered, or how many characters are over the limit.
  • If the text exceeds the limit, you can show a warning state and a message that explains the limit.
  • If users type or paste a longer text, they can see the full text while they decide on how to best shorten it.

Text entered can exceed 20-character limit – live example

Text Area with a Label

You can add a label to the text area.

Text area with a label – live example

Behavior and Interaction

Fixed Height

You can configure the height of the text area to fit the space available on your UI. If the text doesn’t fit into the available space, a scrollbar appears.

Text area with a fixed height

Growing Behaviour

The text area component offers a growing property. If growing is active, the input container grows and shrinks automatically as the user types.

You can configure the minimum and maximum number of lines to be shown. If the text exceeds the maximum number of lines, the text area stops growing and a scrollbar appears.

Growing behavior (minimum 2 lines, maximum 5 lines) – live example

Text Area Counter

If you have set a character limit for the text area but don’t restrict text entry, a character counter is displayed below the text.

If the text is over the limit:

  • The user can continue typing.
  • The counter indicates how many characters are over the limit.
  • We recommend changing the text area to a warning state and displaying an appropriate message.

If the text is pasted into the field, any excess characters are selected automatically.

Show a warning state when the text exceeds the character limit

Responsive Behavior

You can set the maximum number of lines to be shown. The amount of text depends on the size of the screen. On smaller screens, the user can scroll down the text area to see the entire text. To indicate that the text continues, the component shows only half of the last line. This also applies for mobile devices.

Related Links

Components

Implementation

  • Text Area
    (UI5 Web Components documentation)
  • Input
    (UI5 Web Components documentation)

Filter Bar

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

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

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

When to Use

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

Do not use the filter bar:

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

Filter Bar Components

Expanded Filter Bar

The expanded filter bar consists of:

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

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

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

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

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

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

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

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

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

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

Collapsed Filter Bar

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

Collapsed filter bar
Collapsed filter bar

It shows a summary of the filters currently applied:

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

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

“Adapt Filters” Dialog

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

Adapt Filters dialog - list view, hidden values
Adapt Filters dialog - list view, hidden values

The Adapt Filters dialog consists of:

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

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

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

Searching and Displaying Filters in the Dialog

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

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

In the dialog, when a mandatory filter has:

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

In the dialog, users can display the filters:

  • With or without the filter values (2).

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

  • In the list or group view (3).

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

Displaying Filters in the Filter Bar

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

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

In the Adapt Filters footer bar (5):

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

Resetting Filters

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

Adapt Filters dialog - list view, values shown
Adapt Filters dialog - list view, values shown
Adapt Filters dialog - grouped view, hidden values
Adapt Filters dialog - grouped view, hidden values
Adapt Filters dialog - grouped view, values shown
Adapt Filters dialog - grouped view, values shown

Filter Input Controls

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

For Use
A predefined list for single or multiple selection The select control or combo box control
Temporal information The date picker or date range selector
Multi-input fields Suggestions to help the user enter a valid value

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

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

Developer Hint
For development information, see Data Types for the smart filter bar.

Behavior and Interaction

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

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

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

Responsiveness

The name of the view or title is always visible.

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

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

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

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

Examples

Top Tips

Filter Bar

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

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

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

Filter Input Controls

Preset Filter Values

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

Update Mode

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

Related Links

Elements and Controls

Implementation

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
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 L
Single planning calendar - Size M
Single planning calendar - Size M
Single planning calendar - Size S
Single planning calendar - Size S

Components

The single planning calendar consists of the following components:

  1. Header
  2. Toolbar
  3. View switch
  4. Navigation
  5. Date strip
  6. All-day appointment
  7. Timeline
  8. Appointment
  9. Calendar grid
  10. Now marker
Components of the single planning calendar
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
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 10 days - size L
Custom view 3 days - size S
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.

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
Appointment structure
Now marker - Current time replaces the full hour
Now marker - Current time replaces the full hour

Single Planning Calendar Legend

You can highlight special days within the calendar. A legend is used to define the meaning of the highlights. Users open the legend using the legend icon button in the toolbar (  ). Like all other actions in the toolbar, the app developer must add the legend button explicitly.

For details, see the legend sections for the Planning Calendar and Calendar.

Guidelines
Ensure that colors are used consistently within your product area.
Single planning calendar legend
Single planning calendar legend

Behavior and Interaction

Date Picker

The visible period is indicated with the date interval link in the navigation. Clicking the link opens a date picker, which helps the user to navigate quickly to a specific day or week.

Creating an Appointment

We recommend offering a Create action in the toolbar.

The UI for creating the appointment must be implemented at app level. The control provides only the underlying functionality for creating appointments. For most use cases, a dialog works best and is recommended (see sample dialog below).

First day of the week

You can set the day that displays as the first day of the week in the week and month views. Valid values are 0 to 6, starting with Sunday. If no value is set, the default of the used locale is used.

Zooming

To make appointments easier to read, you can implement the zoom behavior using the controls buttonstep input, or slider.

The scaleFactor property controls the zoom level. Its values can be numbers from 1 to 6. The number represents a multiplier for the height of the rows.

Viewing Appointment Details

The UI for viewing appointment details must be implemented at app level. The control provides only the underlying functionality for displaying appointment details. We recommend using a popover to keep the context for the user (see sample popover below).

Working Hours

You can opt to set working hours in the single planning calendar (properties: startHourendHour). 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).

Sticky Header

To keep the context when the user scrolls down the calendar, the header area of the single planning calendar can remain fixed at the top of the screen (property: stickyMode).

At app level, you can choose to have the entire header area sticky (value: All) or only the Navigation area (value: NavBarAndColHeaders).

Drag and Drop

You can enable drag and drop for moving appointments (property: enableAppointmentDragAndDrop). Moving an appointment changes its start and end times (for example, if an appointment is scheduled from 1:00-2:00 PM, the user can drag it and change the time slot to 2:00-3:00 PM). When dragged, the appointment is shown as a ghost element on the mouse cursor. A placeholder indicates the target drop area.

Appointments can also be dragged from or to the area for all-day appointments. When the user drags an all-day appointment to the planning area, a placeholder shows the duration of the appointment after dropping (default = 1 hour). Similarly, dragging a regular appointment to the all-day appointments area transforms it into an all-day appointment (default = 1 day).

For desktop devices, you can also enable the following options:

  • Allow users to create new appointments by clicking, dragging, and releasing on an empty space in the content area (property: enableAppointmentsCreate).
  • Allow users to change the duration of an appointment by clicking and dragging one side of the appointment (property: enableAppointmentsResize).
Warning

To comply with the WCAG 2.2 accessibility standard, the control must offer an alternative to the drag and drop feature. Provide direct access via keyboard shortcuts, which enables single pointer users to make use of virtual on-screen keyboards. Alternatively, use a popover for appointment information and a dialog for creating appointments. For an example, see Single Planning Calendar – Create and Modify Appointments.

Drag and drop
Drag and drop
Drag and drop into the all-day appointments area
Drag and drop into the all-day appointments area
Drag and drop from 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

Implementation

Planning Calendar

The planning calendar allows users to see different appointments at the same time and to create new appointments. It allows the user to display appointments for several objects, such as a team calendar, and compare them to each other.

Usage

Use the planning calendar if:

  • You want to compare objects of the same type with each other over a period of time.
  • You require responsive behavior.
  • You have less than 100 lines in the calendar.

Do not use the planning calendar if:

  • You want to show a calendar for one object and a detailed overview of appointments over a long time interval.
  • You want to show a complex or graphical representation. In this case, please use the Gantt chart.
  • You have more than 100 lines in the calendar. In this case, please use the Gantt chart.

Responsiveness

In size S, the control provides pop-in behavior, which allows the user to see as many appointments as possible and to connect them with the corresponding object. If the toolbar contains too many actions for the space available, the overflow icon appears.

The interval section displaying the hours, days, and months is responsive and shows 12 values in size L, 8 values in size M, and 6 values in size S. You can override this behavior, but you should then check that the responsiveness is still working.

Planning calendar - Size L
Planning calendar - Size L
Planning calendar - Size M
Planning calendar - Size M
Planning calendar - Size S
Planning calendar - Size S

Types

You can define what size of interval the calendar should show, and whether multi selection should be possible. Additionally, the row header and the interval appointments are optional.

The control allows multi-select mode to be shown for the list items. This can be used, for example, to delete multiple objects from the view.

An app development team must decide whether to show the planning calendar with or without multi-select mode, or whether users should be able to switch between the two modes. Hiding the interval appointments of every object is optional.

The planning calendar can also be used without a row header. In this case, the row header disappears and only the appointments are visible. It can be used to show the calendar of one object. Note that the control was built mainly to compare time slots of different objects. For this reason, the time axis is shown horizontally and, depending on the interval, the appointments might shrink to smaller size. In this case, the text is cut off rather than truncated.

Components

This section describes the various components of the planning calendar.

Parts of the planning calendar
Parts of the planning calendar

The control consists of different parts:

  1. Header
  2. Toolbar
  3. View switch
  4. Navigation
  5. Time strip for hours/days/months
  6. Row header
  7. Row
  8. List item
  9. Interval appointment
  10. Appointment

1. Header

The header contains the toolbar and the navigation.

2. Toolbar

The toolbar consists of the calendar title (optional) and the toolbar actions, including a default view switch. You can add generic and app-specific actions that are relevant for your use case (such as creating an appointment, search, settings, showing the calendar legend, and so on). Always place actions that affect the entire calendar in the toolbar.

For more information, check out the toolbar guideline article.

The generic actions are as follows:

Search
Create Appointment
Add New Contact (icon: add-contact)
Multi-Select Mode (icon: multi-select)
Legend (icon: legend)
Settings (icon: action-settings)
Full Screen (icon: full-screen/exit-full-screen)

3. View switch

The view switch allows the user to switch between different time intervals (calendar views). Depending on the number of available calendar views, the view switch can be a segmented button (four views or less) or a select control (five views or more).

The 1 Month view shows an entire month. On desktop devices, the 1 Month view always displays an interval of 31 days. When the displayed month is shorter (28, 29, 30 days), days from the following month are displayed. They have a different visual state and serve as navigation to the following month.

The 1 Month view has an additional style for half-column appointment distribution, which is mainly used to avoid overlapping. The property appointmentRoundWidth can be set to “HalfColumn” or “None” (default). Currently, the width of the appointment is always rounded to 12 hours.
Note: This property is also applied when the calendar interval type is Days and the view shows more than 20 days.

On size M and Size S, the 1 Month view is adaptive. It consists of a calendar and a list of appointments for the selected day.

If you offer the 1 Week view, we strongly recommend displaying a different number of days in the Days view (more or less than seven). Otherwise, the user might be confused, as navigation for the two views differs.

The default calendar views are Hours, Days, Months, 1 Week, and 1 Month. The app developer can choose which views to include, depending on the use case, and how many values are shown for each view. App developers can change the default number of values shown, but they should then ensure that the app is still responsive. The app developer can also create custom views.

Relative views

When you need to display a period that is not connected to a certain time/date, you can map the calendar to relative dates (in contrast to absolute dates, such as, “Week 1”, “Week 2”). For example, when you would like to divide the year into quarters.

The application developer specifies the names of the intervals in the time strip and the index picker, as well as the size of the interval. The index picker then configures how many days are in one interval. All this happens in the PlanningCalendarView, once the newly created relative property is set to “true”.

In addition, the application developer sets a minDate in the planning calendar, determining the start date of the relative views.

4. Navigation

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

5. Time strip for hours/days/months

The time strip reflects the selected view, and shows the hours, days or months that are currently visible. The first day of the week can be defined. If not defined, the default is taken from the current user locale.

In all views that show days (Days, 1 Week, 1 Month), you can display calendar weeks in an extra line below the time strip (property: showWeekNumbers).

6. Row header

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

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

7. Row

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

8. List item

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

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

9. Interval appointment

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

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

10. Appointment

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

There are four types of appointments:

  • Regular: Displayed in two rows. One-row display is also possible if the appointmentsReducedHeight property is set to “true”.
  • Half-size: Always displayed in one row, shows the title.
  • Large: Always displayed in three rows, also shows the description for each appointment (if available).
  • Automatic: The number of rows is determined automatically.
    Appointment Info Rows
    Title only 1 row
    Title + text
    or:
    Title + description
    2 rows
    Title + text + description 3 rows

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

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

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

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

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

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

Planning Calendar Legend

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

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

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

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

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

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

Guidelines
Ensure that colors are used consistently within your product area.

The Appointments section contains the color values for the available appointment types. The app developer has to define explicitly which color represents which type. The planning calendar legend does not take the color automatically from the planning calendar.

If combined appointments in the calendar are of the same type (in Months view), they take the color of that type. Combined appointments of different types are marked gray. We also recommend adding the gray color for mixed combined appointments to the Appointments section in the legend.

Planning calendar legend
Planning calendar legend
Developer Hint
To prevent waiting time, app developers should load the sap.ui.unified library.

Behavior and Interaction

To create an appointment, the user must trigger an action by clicking the Create button in the toolbar. You can also configure the control to create a new appointment when the user clicks directly on a row.

The user can click the appointment to see further details. The app development team must define what kind of information is then shown. For example, clicking an appointment can trigger a popover with detailed information.

Users can select more than one appointment at a time via Ctrl/Cmd + click. If the multipleAppointmentsSelection property is set to “true”, every appointment that the users click is selected.

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

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

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

View switch

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

Today

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

Back and forward navigation

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

Date picker

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

Snapping Header

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

Header snaps to top when scrolling down
Header snaps to top when scrolling down

Drag and Drop

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

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

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

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

Combined appointments and interval appointments are not draggable.

Drag and drop is only available on supporting browsers.

Warning
To comply with the new WCAG 2.2 accessibility standard, the control must offer an alternative to the drag and drop feature. Provide direct access via keyboard shortcuts, which enables single pointer users to make use of virtual on-screen keyboards. Alternatively, use a popover for appointment information and a dialog for creating appointments. For an example, see Planning Calendar – With Appointments Modification.
Drag and drop
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.

Resources

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

Elements and Controls

Implementation

Checkbox

A checkbox lets the user set a binary value (such as “true/false”). When the user clicks the checkbox, it toggles between checked and unchecked. Checked means that the state described by the checkbox text applies, or that the item has been chosen.

The checkbox text describes the positive action (as in “true” or “yes”). The text can be either a label control to the left of the checkbox, or a checkbox text that appears to the right of the box.

  • If there is only one checkbox, you can use a label or text depending on the form format.
  • If there is more than one checkbox, the label describes the whole group of checkboxes. In this case, use the text property of the checkbox to describe the individual checkboxes.

Within a group of checkboxes, each checkbox can be checked or unchecked. The user can check multiple options.

A checkbox does not apply a setting right away; the changes take effect after user confirmation via a triggering action button (such as Save).

Checkbox enabled/disabled
Checkbox enabled/disabled

Usage

Use the checkbox control if:

  • Only one option can be selected or deselected, for example to accept terms of use. Use it only if the meaning is obvious (single checkbox).
  • You have a group or a list of options that can be selected independently of each other (checkbox group).
  • Your use case requires all available options to be displayed right away without any user interaction (also in read-only cases).
  • The values of the option list are primary information and need to be displayed right away.
  • Changes to the settings need to be confirmed and reviewed by the user before they are submitted. This helps prevent users from changing settings accidentally.
  • You want to group multiple suboptions under a parent option, and require an intermediate selection state (tri-state). The tri-state indicates that some (but not all) suboptions are selected.

Do not use the checkbox control if:

  • The user needs to choose multiple options from a large list. Use a multi-combo box instead.
  • The user can choose only one option from a list. For a small list, use a radio button group instead. For a large list, use the select control or a list with multi-selection functionality.
  • You want to offer two options for a “yes/no” or “on/off” type of decision. Consider using a switch control instead.
  • The user needs to perform instantaneous actions that do not need reviewing or confirming. Consider using the switch control instead.
  • There is not enough space available on the screen. Use the combo box control instead.

Responsiveness

A checkbox can appear in two different sizes. In cozy mode, it is bigger than it is in compact mode. This makes the checkbox easier to select on touch devices. For more information on cozy and compact modes, see the article on content density.

Compact and cozy mode
Compact and cozy mode

In both sizes, the touch/click area around the checkbox is bigger than the checkbox itself, making the checkbox easier to select. Clicking inside this area toggles the checkbox.

Note: Because the touch/click area does not include the label on the left, clicking the label will not toggle the checkbox.

Checkbox touch/click area without label
Checkbox touch/click area without label
Checkbox touch/click area with label
Checkbox touch/click area with label

Layout

The checkbox control consists of a box and a text that describes the purpose of the checkbox.

If the checkbox is checked, an indicator is shown inside the box.

Although the clickable area to select/deselect a checkbox covers a wider area than the box (see the Responsiveness section), the focus is indicated by a dotted line that surrounds only the box.

If the checkbox appears alone inside a form, the text can be omitted if the label in front of the checkbox takes over its function.

Note: Because the touch/click area does not include the label on the left, clicking the label does not toggle the checkbox.

If there are several options to choose from in a form, the label describes the entire checkbox group, and the texts describe the individual checkboxes.

Since checkbox texts are also a type of label, use title case to be consistent with other labels. If the label is long, it can wrap in order to fit the text into the visible area of the content holder. There is no limit on the number of lines a text can wrap.

Exception: If one or several of the checkbox texts is very long, or is formulated as a phrase, use sentence case and appropriate ending punctuation.

For forms with labels above the fields, place the label above the checkbox group, or do not use a label. For a single checkbox, use only a checkbox text.

For forms with labels to the left of the field, place the label next to the group, aligned with the first checkbox field, or do not use a label. For a single checkbox, use only a label, or only a checkbox text.

Developer Hint
Do not use empty labels to arrange the checkboxes. Creating a label in front of each checkbox and leaving the text empty looks fine – nobody sees the label, and the checkboxes are aligned correctly underneath each other. However, the screen reader will notice these labels and read each of them as “label”. Instead, use the layout data property (layoutData) for the checkbox. In this property, force a line break (linebreak) and set the value of the indents in sizes L and M (indentL, indentM) according to the value of the label span in the simple form (labelSpanL, labelSpanM).
Checkbox layout
Checkbox layout
Short checkbox text in title case; Long checkbox text in sentence case
Short checkbox text in title case; Long checkbox text in sentence case
Checkbox text wrap
Checkbox text wrap
Checkbox group with label aligned to the left or on top
Checkbox group with label aligned to the left or on top
Checkbox group without label
Checkbox group without label
Single checkbox with label or with text
Single checkbox with label or with text

Behavior and Interaction

Clicking a checkbox toggles the state of the checkbox between checked and unchecked.

Tri-State

The main purpose of this state is to represent the mixed selection states of dependent input fields. If some (but not all) of the dependent fields are selected, the checkbox shows a partially selected state. This is only a visual state and can’t be achieved by a direct user interaction.

Checkbox interaction states
Checkbox interaction states

Properties

You can set the width of the element containing the checkbox and the text manually (property: width).

If the text exceeds the available width, it can wrap. The touchable area for toggling the checkbox ends where the text ends.

If the width allows more space than the text requires, white space is added. The touchable area for toggling the checkbox is increased according to the manually-set width.

The text can be positioned manually in this space (property: textAlign). However, we do not recommend using the right-align option, which can result in a large amount of white space between the checkbox and the checkbox text.

States

If a checkbox is part of an editable form, it can be edited in when the form is in edit mode. In display mode, the checkbox uses its “display-only” state (property: displayOnly), and two icons replace it to represent the checked and unchecked states.

If the checkbox appears in a read-only form, set the checkbox to read-only (property editable = “false”).

Do not combine the settings “disabled” and “read-only”. This is technically possible, but does not make any sense.

The checkbox can represent a mixed selection state, or tri-state (property: partiallySelected). The visual state depends on the value of the selected property.

Don't
Checkbox text - Don't format the checkbox incorrectly
Checkbox text - Don't format the checkbox incorrectly
Checkbox interaction value states
Checkbox interaction value states

Resources

Elements and Controls

Implementation

Smart Field

The smart field creates different user input controls and their read-only equivalents based on an OData (Open Data Protocol) service and its annotations. It comes with additional built-in features, such as autocomplete and suggestions, value help dialogrecently used and recommended valuesvalidation, and message handling.

Information
The smart field is only available for OData version 2.

When to Use

Use the smart field if:

  • You use an OData service for your app (OData version 2 only).
  • The feature set of the smart field fits your app. In this case, the smart field is faster to implement.
  • You use the smart table and your app is not performance-critical. The smart field offers more flexibility than the controls provided directly by the smart table, especially for editing.
  • You use a smart form.

Do not use the smart field if:

  • You use a different technology to OData version 2. Use the corresponding controls directly.
  • You need a different control for entering or displaying data, such as multi input, a multi combo box, step input, a radio button, or a title. In this case, use the corresponding control directly.
  • You need a different dialog for offering value help, such as the select dialog or table select dialog.
  • You use the smart table and your app is performance-critical. In this case, the controls offered directly by the smart table offer less flexibility but better performance.

Components

The smart field consists of a basic UI element and an optional label. The following UI elements are available:

 For details, see the corresponding guideline topics. 

User Input Control

The smart field chooses the control automatically based on the data type (Edm type) and annotations of the OData service and additional properties. The following controls are used:

Read-Only Edit Edm Types / Annotations / Properties Comment
Single-line text Text Input field Edm.String

Configuration: controlType, value: input

Combo box Edm.String

Configuration: controlType, value: dropDownList

Select Edm.String

Configuration: controlType, value: selection

Multi-line text Text Text area Edm.String

MultiLineText

Decimal numbers Text

Object number

One or two input fields
(for number and unit)
Edm.Int16, Edm.Int32, Edm.Int64,
Edm.SByte, Edm.Byte,
Edm.Single, Edm.Float, Edm.Double,
Edm.Decimal
Precision, Scale
Status information Object status Edm.String

criticality, criticalityRepresentationType

Text and ID Text

Object identifier

Object status

Input field TextArrangement

controlProposal

displayBehavior

textInEditModeSource, sap:text,
fetchValueListReadOnly

The following patterns can be selected via displayBehavior:

  • Text (ID)
  • ID (Text)
  • Text
  • ID
Links
(with/without quick view)
Link

Smart link

Edm.String

IsURL, url

semanticObjectController

Dates Text Date picker Edm.DateTime

sap:display-format=”Date”

IsCalendarDate

Configuration: controlType

Dates and times Text Date/time picker Edm.DateTime

Edm.DateTimeOffset

Times Text Time picker Edm.Time
Fiscal periods Text Input field IsFiscalYear, IsFiscalPeriod,
IsFiscalYearPeriod,
IsFiscalQuarter, IsFiscalYearQuarter,
IsFiscalWeek, IsFiscalYearWeek,
IsDayOfFiscalYear
Amounts with currencies Text One or two input fields ISOCurrency or sap:unit with sap:semantics=”currency-code”
Phone numbers Text Input field IsPhoneNumber
Email Text Input field IsEmailAddress
Boolean Checkbox Checkbox Edm.Boolean
Text Combo box Edm.Boolean

valueList

displayBehavior

The text in display mode can be influenced via displayBehavior:

  • Yes/No
  • True/False
  • On/Off
Guidelines

  • Set a default value whenever appropriate (annotation: text, property: value).
  • To show a static unit of measurement, use a description (annotation: text).
  • To display a text and ID in the same place, use the format Text (ID) wherever possible. Use another format only if displaying the text doesn’t make any sense. Be careful when using the text arrangement options in tables: end users will only be able to sort, group, or filter based on the ID, even if the ID isn’t visible.
  • If you are not using the smart field within a smart form or smart table, label the smart field with a smart label (annotation: label, properties: textLabel, showLabel). The standard label doesn’t know the inner structure of a smart field.
  • You can set a tooltip (annotation: QuickInfo), but this should usually be avoided. See Using Tooltips.
  • If data entry is expected in a specific format, set a placeholder (property: Placeholder).

Developer Hint
Performance: Using the TextArrangement annotation to display both the text and ID (in any order) triggers two requests to the back end.

Behavior and Interaction

Context

You can use the smart field in different contexts
(property: controlContext):

  • Standalone
  • Within a form (depending on the form layout)
  • Within a table (depending on the table type)

The context influences:

  • Labels: In most cases, forms provide the label automatically.
  • Empty values in display mode: In forms, empty values are shown as a dash. In tables, the field remains blank. In popins, empty values are shown as a dash because the popin is similar to a form in a table.
  • How units of measurement are displayed
Guidelines

  • If the width is not handled by the context, set a meaningful width for the smart field, based on the expected data (property: Width).
  • If you use a “standalone” smart field  in a form-like arrangement, use a dash to show an empty value in display mode.

Switching Between Edit and Display Mode

Switching between edit and display mode can be controlled manually (annotation: FieldControl, property: editable) or automatically by the containing smart form or smart table (property: contextEditable).

Smart field as a select with 'required' indicator in edit mode
Smart field as a select with 'required' indicator in edit mode
The same smart field in display mode
The same smart field in display mode
Guidelines

  • Define which fields should be editable (annotations: updateable, creatable, updateable-path, InsertRestrictions, UpdateRestrictions, computed, immutable, fieldControl, fieldControlType).
  • For fields with a unit of measurement, define whether the unit of measurement is editable or static (annotation: FieldControl, property: uomEditable).
  • Make sure that the full text is shown in display mode (property: wrapping), unless this is handled differently for the corresponding context (for example, see guidelines for content in the grid table).
  • When you display the text and ID, the smart field automatically displays both values in display mode, but only the ID in edit mode (annotation: TextArrangement). In most cases, it makes sense to also display both values in edit mode (annotation: sap:text, property: textInEditModeSource, aggregation: Configuration with property: displayBehavior).

Suggestions and Value Help

You can enable suggestions for controls that offer this feature (property: showSuggestions). The list of suggestible values must be provided (annotation: ValueList or ValueListWithFixedValues only for Edm.String, property: entitySet). This list can contain several attributes and is also used for the value help dialog. You can restrict the number of attributes from this list to be shown as suggestions, while all attributes are shown within the value help dialog.

Autocomplete is enabled automatically.

For input fields, the value help dialog is also created automatically. Hide it if it is not needed (property: showValueHelp). The table in the value help dialog can be filled with initial content (annotation: ValueList, property: fetchValues, sap.ui.comp.smartfield.Configuration, property: preventInitialDataFetchInValueHelpDialog)

Both the value help dialog and the suggestion list can be prefiltered (annotation: ValueList, property: valueListParameterIn). The selected items can be used to prefilter other fields (annotation: ValueList, property: ValueListParameterOut). The corresponding filter settings are visible. “Invisible” prefiltering is also supported. To use this option, provide the exact matching filter value (Common.ValueListParameterConstant).

If a value has been entered in the smart field, this value is transferred to the search field of the value help dialog automatically. In the value help dialog, individual values can be valid, deprecated, or revoked. Revoked values are hidden from the value help (annotation: IsConfigurationDeprecationCode).

The following controls are used to offer suggestions or value help:

Smart field as a combo box
Smart field as a combo box
Smart field as an input field with suggestions, auto complete, and a value help button
Smart field as an input field with suggestions, auto complete, and a value help button
The automatically generated value help dialog for the same smart field
The automatically generated value help dialog for the same smart field

Recently Used Values

Input fields, combo boxes, and selects can provide up to five recently used values automatically on focus if suggestions or value help are available. This can be turned on or off per field (property: historyEnabled). Recently used values are shown by default for input fields, but not for combo boxes and selects.

Guidelines
Do not show recently used values for a field if:

  • There are only a small number of options.
  • The field contains personal sensitive data (annotation: IsPotentiallySensitive).
  • It is unlikely that the same values will be selected again and again.

Recommended Values

In addition to recently used values, a smart field can show recommended values (annotation: RecommendationState).

The corresponding smart field is highlighted and/or prefilled:

  • If no recommendation is available or the current user input matches the recommendation, the smart field is shown in the default state.
  • If a recommendation is available and there is no user input, the smart field is shown in the information state.
  • If a recommendation is available and it differs from the current user input, the smart field is displayed in the warning state.

The recommended values are shown as soon as the user focuses on the smart field.

Validation

The smart field offers the following validations automatically:

  • Validation for required fields: This can be done on the client or server side (property: clientSideMandatoryCheck, annotation: Nullable).
  • Validation for a group of fields: Validation is triggered when the focus moves outside a group of fields, rather than when a single field loses the focus. A group is defined by all smart fields that share the same field group ID (property: fieldGroupIds).
  • Validation for the maximum length of user input: Validation is triggered when a field loses the focus or the ENTER key is pressed (property: maxLength).
  • Validation for combo boxes: Checks if the value entered is available in the dropdown list (property: fixedValueListValidationEnabled).

The validation result is indicated by a value state (property: showValueStateMessage).

When the user edits a smart field showing a text and ID, you can allow any kind of input to avoid unnecessary validation issues (annotation: ValueListNoValidation).

Examples:

  • Allowing the user to enter additional values (which are not in the suggestion list)
  • Typing a text instead of an ID to filter down the suggestion list
  • Using the smart field in a draft
Automatic validation
Automatic validation

IDs

The smart field offers automatic validation for number-only ID fields (annotations: IsDigitSequence or sap:display-format="NonNegative"):

  • It checks for non-negative numbers.
  • It shows values containing only “0” digits as empty.
  • It does not show leading zeros.

Units

For decimal number fields and for fields that show an amount with a currency, you can add a unit of measure  (annotations: unit, sap-unit with sap:semantics="unit-of-measure" or sap:semantics="currency-code", property: uomVisible). In display mode, the unit is added to the corresponding number. In edit mode, the unit is shown either as text or, if editable, as a second input field (properties: uomEditable, uomEnabled).

Smart field showing an amount with a currency in display mode
Smart field showing an amount with a currency in display mode
The same smart field in display mode
The same smart field in display mode

Sensitive Data

Sensitive data, such as passwords, can be masked. The text is then replaced with asterisks (annotations: IsPotentiallySensitive, masked).

Capitalizing Text Input

Text input can be capitalized automatically (property: IsUpperCase).

States

Smart fields support the following states (annotation: fieldControl):

  • Editable or display only (additional annotations: updateable, creatable, updatable-path, InsertRestrictions, UpdateRestrictions, property: editable)
  • Enabled or disabled
  • Visible or hidden (additional annotations: property: visible, annotation: sap:visible)
  • Required: If set, the smart field must contain a value when validated. This is indicated by an asterisk next to the corresponding label (additional annotation: Nullable, property: mandatory).

The following states for a unit of measurement can be set independently of the corresponding field:

  • If editable, a unit of measurement can be enabled or disabled (property: uomEnabled)
  • The unit of measurement can be visible or hidden (property: uomVisible)
Developer Hint
In the SAPUI5 SDK API Reference for the smart field, the display only state is referred to as read only.

Dependencies between Smart Fields

If the content of a smart field is changed, you can trigger additional changes to other fields on the UI (annotation: SideEffects).

Content Alignment

You can change the horizontal alignment of the text within any kind of input field  (property: textAlign).

Guidelines
Follow the alignment rules for the respective context (responsive table, other tables, form). If you are using the standalone option for the smart field (without a context), apply the rules for the corresponding input fields.

Responsiveness

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

Top Tips

  • Always label a smart field if it is not inside a table context.
  • Use suggestions with autocomplete whenever possible and meaningful.
    • Do not show suggestions if there are only a few choices.
    • Use recently used values as appropriate.
    • Reduce the number of attributes shown in the suggestion list to a maximum of 4 or 5.
  • Make use of validation features.

Properties

The following properties, aggregations, and associations are available for sap.ui.comp.smartfield.SmartField:

  • The property: expandNavigationProperties is deprecated. Do not use it.
  • The property: importance hides the field if the smart field is placed in a smart form, depending on the importance setting of the smart form. End users have no possibility to show the corresponding fields again. Do not use this property.
  • The property: jsontype is deprecated. Do not use it.
  • The property: name is used in HTML forms that send data to the server via “Submit”.
  • The property: uomEditState is for internal use only. Do not use it.
  • The property: proposedControl is deprecated. Do not use it.
  • The property: textDirection provides support for reading directions in different locales.
  • The aggregation: controlProposal is deprecated. Do not use it.
  • The association: ariaLabelledBy can be used for linking additional labels to the smart field.

Related Links

Elements and Controls

Implementation

Date Range Picker

The date range picker allows users to enter a date range by either typing two dates in the input field or selecting a date range in the calendar.

The date range picker can also be used to enter a single date.


Basic date range picker – live example

When to Use

Do

Use the date range picker if:

  • Users need to enter a date range and you know that the keyboard is not the primary device used for navigating the app.
Don't

Don’t use the date range picker if:

  • Users need to enter a date and a time. In this case, use the date picker or time picker instead.
  • Selecting ranges is not the user’s primary goal. In this case, use the simple date picker.
  • If the keyboard is the primary device used for navigating the app, use two input fields. This allows the user to jump quickly from field to field.

Anatomy

  1. Date input field: Field for typing in dates directly. It contains a mask.
  2. Text: A placeholder or the selected/typed text.
  3. Date range picker button: Button that opens the calendar.
  4. Calendar: See the calendar guideline for more details.
  5. Current date
  6. Selected date range
Anatomy of the date range picker
Anatomy of the date range picker

Variants

Restricted Date Range

You can set minimum and maximum dates. In this case, the user can only select dates within the approved range.

Predefined Date Range

You can set a predefined date range that is selected by default when the user opens the calendar. The user can still change the dates.

Date Display in the Input Field

You can specify the format of the dates in the input field. Supported formats are based on the Unicode Locale Data Markup Language (LDML) date format notation.

You can also specify the symbol that separates the start and end dates.



Minimum/maximum dates, specific date format – live example
Predefined date range, custom delimiter – live example

Behavior and Interaction

Selection

Date range: After selecting a start date, hovering over another date turns the dates in between to light blue, indicating that they are in the selected range. When the user selects an end date, the calendar closes and the range appears in the date input field.

Single date: To enter a single date, the user can type one date into the input field, or select the same day as the start and end date in the calendar.

Shortcuts

The following shortcuts are available for entering specific dates:

  • “today”
  • “yesterday”
  • “in x days”
  • “x days ago”
  • “yesterday – today”
  • “x days ago – in x days”

Restricted Date Range

If minimum and maximum dates have been set, selection and navigation to dates outside this range is disabled.

Formatting

If the user types the date in the input field, it must fit the required date format. For example, if the format pattern is “yyyy-MM-dd”, a valid user input would be “2023-07-30”.

Related Links

Implementation

Text Area

The text area is an input component that allows the user to enter several lines of text.

Basic text area – live example

When to Use

Do

Use the text area:

  • If users need to enter more than one line of text.
Don't

Don’t use the text area:

  • If you only want users to enter a single line of text. Use the input component instead.

Anatomy

  1. Input field: Container in which a user enters text.
  2. Text: Placeholder or typed text. The placeholder is an optional prompt text that is displayed when the input field is empty.
  3. Scrollbar
  4. Counter: If you have set a character limit without restricting text input, the counter indicates how many characters are left, or how many characters exceed the limit.
Anatomy of the text area
Anatomy of the text area

Variants

Text Area with Character Limit

You can set a character limit for the text. In this case, you have two options for handling the text input:

Text is cut off after the character limit

Once the character limit has been reached, users can no longer type or enter additional text. Pasted text is cut off. This is the default setting.

No text entry after 20-character limit is reached – live example

Text can exceed the character limit

You can allow the user to enter text that exceeds the character limit. We strongly recommend using this variant because it offers users much better orientation:

  • A character counter indicates how many characters are can still be entered, or how many characters are over the limit.
  • If the text exceeds the limit, you can show a warning state and a message that explains the limit.
  • If users type or paste a longer text, they can see the full text while they decide on how to best shorten it.

Text entered can exceed 20-character limit – live example

Text Area with a Label

You can add a label to the text area.

Text area with a label – live example

Behavior and Interaction

Fixed Height

You can configure the height of the text area to fit the space available on your UI. If the text doesn’t fit into the available space, a scrollbar appears.

Text area with a fixed height

Growing Behaviour

The text area component offers a growing property. If growing is active, the input container grows and shrinks automatically as the user types.

You can configure the minimum and maximum number of lines to be shown. If the text exceeds the maximum number of lines, the text area stops growing and a scrollbar appears.

Growing behavior (minimum 2 lines, maximum 5 lines) – live example

Text Area Counter

If you have set a character limit for the text area but don’t restrict text entry, a character counter is displayed below the text.

If the text is over the limit:

  • The user can continue typing.
  • The counter indicates how many characters are over the limit.
  • We recommend changing the text area to a warning state and displaying an appropriate message.

If the text is pasted into the field, any excess characters are selected automatically.

Show a warning state when the text exceeds the character limit

Responsive Behavior

You can set the maximum number of lines to be shown. The amount of text depends on the size of the screen. On smaller screens, the user can scroll down the text area to see the entire text. To indicate that the text continues, the component shows only half of the last line. This also applies for mobile devices.

Related Links

Components

Implementation

  • Text Area
    (UI5 Web Components documentation)
  • Input
    (UI5 Web Components documentation)

Date Range Picker

The date range picker allows users to enter a date range by either typing two dates in the input field or selecting a date range in the calendar.

The date range picker can also be used to enter a single date.


Basic date range picker – live example

When to Use

Do

Use the date range picker if:

  • Users need to enter a date range and you know that the keyboard is not the primary device used for navigating the app.
Don't

Don’t use the date range picker if:

  • Users need to enter a date and a time. In this case, use the date picker or time picker instead.
  • Selecting ranges is not the user’s primary goal. In this case, use the simple date picker.
  • If the keyboard is the primary device used for navigating the app, use two input fields. This allows the user to jump quickly from field to field.

Anatomy

  1. Date input field: Field for typing in dates directly. It contains a mask.
  2. Text: A placeholder or the selected/typed text.
  3. Date range picker button: Button that opens the calendar.
  4. Calendar: See the calendar guideline for more details.
  5. Current date
  6. Selected date range
Anatomy of the date range picker
Anatomy of the date range picker

Variants

Restricted Date Range

You can set minimum and maximum dates. In this case, the user can only select dates within the approved range.

Predefined Date Range

You can set a predefined date range that is selected by default when the user opens the calendar. The user can still change the dates.

Date Display in the Input Field

You can specify the format of the dates in the input field. Supported formats are based on the Unicode Locale Data Markup Language (LDML) date format notation.

You can also specify the symbol that separates the start and end dates.



Minimum/maximum dates, specific date format – live example
Predefined date range, custom delimiter – live example

Behavior and Interaction

Selection

Date range: After selecting a start date, hovering over another date turns the dates in between to light blue, indicating that they are in the selected range. When the user selects an end date, the calendar closes and the range appears in the date input field.

Single date: To enter a single date, the user can type one date into the input field, or select the same day as the start and end date in the calendar.

Shortcuts

The following shortcuts are available for entering specific dates:

  • “today”
  • “yesterday”
  • “in x days”
  • “x days ago”
  • “yesterday – today”
  • “x days ago – in x days”

Restricted Date Range

If minimum and maximum dates have been set, selection and navigation to dates outside this range is disabled.

Formatting

If the user types the date in the input field, it must fit the required date format. For example, if the format pattern is “yyyy-MM-dd”, a valid user input would be “2023-07-30”.

Related Links

Implementation

Switch

The toggle switch mimics a physical switch. It allows users to set individual features (such as personalization or display settings) to either active or inactive.

Label, optional text, and switch
Label, optional text, and switch

Usage

Use the switch if:

  • You want to enable users to set something as active or inactive (for example, within a dialog).
  • You need to clearly show the mode or state of a setting.
  • The change takes immediate effect.

Do not use the switch if:

  • The user has to choose several options or perform extra steps for changes to become effective.
  • It’s not clear if the control is showing a state or an action. In this case, use a checkbox instead.

Types

There are three switch types: basic, semantic, and with optional text.

Basic Switch (Default)

The basic switch changes something to active or inactive. This is the default switch.

Default switch
Default switch

Semantic Switch

The semantic switch changes something to ‘positive’ or ‘negative’. An icon is displayed automatically for each semantic state and cannot be changed.

Semantic switch
Semantic switch

Switch with Optional Text

You can display a text (sap.m.text or sap.m.objectstatus) next to the switch to indicate what the ‘active’ and ‘inactive’ states mean in your specific use case. Keep the text succinct.

Position the text next to the switch:

  • Left of the switch in left-to-right writing systems
  • Right of the switch in right-to-left writing systems
Switch with optional text
Switch with optional text
Semantic switch with optional text
Semantic switch with optional text

On/Off Switch

Technically, the switch can also display 2-3 letters within the switch.

 This design is obsolete. To avoid localization issues, never use text inside a switch.

Don't
Switch containing text
Switch containing text

Behavior and Interaction

The control supports mouse, touch, keyboard and screen reader interaction.

The user can switch between two states: active or inactive. The state is changed by moving the toggle from one side to another or by clicking the empty side. The toggle then moves over.

Styles

Switches can have different states and markups, but are always ‘active’ or ‘inactive’. The control supports an enabled, hovered, and disabled state.

Enabled semantic switch
Enabled semantic switch
Hovered semantic switch
Hovered semantic switch
Disabled semantic switch
Disabled semantic switch

Resources

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

Elements and Controls

Implementation

Checkbox

A checkbox lets the user set a binary value (such as “true/false”). When the user clicks the checkbox, it toggles between checked and unchecked. Checked means that the state described by the checkbox text applies, or that the item has been chosen.

The checkbox text describes the positive action (as in “true” or “yes”). The text can be either a label control to the left of the checkbox, or a checkbox text that appears to the right of the box.

  • If there is only one checkbox, you can use a label or text depending on the form format.
  • If there is more than one checkbox, the label describes the whole group of checkboxes. In this case, use the text property of the checkbox to describe the individual checkboxes.

Within a group of checkboxes, each checkbox can be checked or unchecked. The user can check multiple options.

A checkbox does not apply a setting right away; the changes take effect after user confirmation via a triggering action button (such as Save).

Checkbox enabled/disabled
Checkbox enabled/disabled

Usage

Use the checkbox control if:

  • Only one option can be selected or deselected, for example to accept terms of use. Use it only if the meaning is obvious (single checkbox).
  • You have a group or a list of options that can be selected independently of each other (checkbox group).
  • Your use case requires all available options to be displayed right away without any user interaction (also in read-only cases).
  • The values of the option list are primary information and need to be displayed right away.
  • Changes to the settings need to be confirmed and reviewed by the user before they are submitted. This helps prevent users from changing settings accidentally.
  • You want to group multiple suboptions under a parent option, and require an intermediate selection state (tri-state). The tri-state indicates that some (but not all) suboptions are selected.

Do not use the checkbox control if:

  • The user needs to choose multiple options from a large list. Use a multi-combo box instead.
  • The user can choose only one option from a list. For a small list, use a radio button group instead. For a large list, use the select control or a list with multi-selection functionality.
  • You want to offer two options for a “yes/no” or “on/off” type of decision. Consider using a switch control instead.
  • The user needs to perform instantaneous actions that do not need reviewing or confirming. Consider using the switch control instead.
  • There is not enough space available on the screen. Use the combo box control instead.

Responsiveness

A checkbox can appear in two different sizes. In cozy mode, it is bigger than it is in compact mode. This makes the checkbox easier to select on touch devices. For more information on cozy and compact modes, see the article on content density.

Compact and cozy mode
Compact and cozy mode

In both sizes, the touch/click area around the checkbox is bigger than the checkbox itself, making the checkbox easier to select. Clicking inside this area toggles the checkbox.

Note: Because the touch/click area does not include the label on the left, clicking the label will not toggle the checkbox.

Checkbox touch/click area without label
Checkbox touch/click area without label
Checkbox touch/click area with label
Checkbox touch/click area with label

Layout

The checkbox control consists of a box and a text that describes the purpose of the checkbox.

If the checkbox is checked, an indicator is shown inside the box.

Although the clickable area to select/deselect a checkbox covers a wider area than the box (see the Responsiveness section), the focus is indicated by a dotted line that surrounds only the box.

If the checkbox appears alone inside a form, the text can be omitted if the label in front of the checkbox takes over its function.

Note: Because the touch/click area does not include the label on the left, clicking the label does not toggle the checkbox.

If there are several options to choose from in a form, the label describes the entire checkbox group, and the texts describe the individual checkboxes.

Since checkbox texts are also a type of label, use title case to be consistent with other labels. If the label is long, it can wrap in order to fit the text into the visible area of the content holder. There is no limit on the number of lines a text can wrap.

Exception: If one or several of the checkbox texts is very long, or is formulated as a phrase, use sentence case and appropriate ending punctuation.

For forms with labels above the fields, place the label above the checkbox group, or do not use a label. For a single checkbox, use only a checkbox text.

For forms with labels to the left of the field, place the label next to the group, aligned with the first checkbox field, or do not use a label. For a single checkbox, use only a label, or only a checkbox text.

Developer Hint
Do not use empty labels to arrange the checkboxes. Creating a label in front of each checkbox and leaving the text empty looks fine – nobody sees the label, and the checkboxes are aligned correctly underneath each other. However, the screen reader will notice these labels and read each of them as “label”. Instead, use the layout data property (layoutData) for the checkbox. In this property, force a line break (linebreak) and set the value of the indents in sizes L and M (indentL, indentM) according to the value of the label span in the simple form (labelSpanL, labelSpanM).
Checkbox layout
Checkbox layout
Short checkbox text in title case; Long checkbox text in sentence case
Short checkbox text in title case; Long checkbox text in sentence case
Checkbox text wrap
Checkbox text wrap
Checkbox group with label aligned to the left or on top
Checkbox group with label aligned to the left or on top
Checkbox group without label
Checkbox group without label
Single checkbox with label or with text
Single checkbox with label or with text

Behavior and Interaction

Clicking a checkbox toggles the state of the checkbox between checked and unchecked.

Tri-State

The main purpose of this state is to represent the mixed selection states of dependent input fields. If some (but not all) of the dependent fields are selected, the checkbox shows a partially selected state. This is only a visual state and can’t be achieved by a direct user interaction.

Checkbox interaction states
Checkbox interaction states

Properties

You can set the width of the element containing the checkbox and the text manually (property: width).

If the text exceeds the available width, it can wrap. The touchable area for toggling the checkbox ends where the text ends.

If the width allows more space than the text requires, white space is added. The touchable area for toggling the checkbox is increased according to the manually-set width.

The text can be positioned manually in this space (property: textAlign). However, we do not recommend using the right-align option, which can result in a large amount of white space between the checkbox and the checkbox text.

States

If a checkbox is part of an editable form, it can be edited in when the form is in edit mode. In display mode, the checkbox uses its “display-only” state (property: displayOnly), and two icons replace it to represent the checked and unchecked states.

If the checkbox appears in a read-only form, set the checkbox to read-only (property editable = “false”).

Do not combine the settings “disabled” and “read-only”. This is technically possible, but does not make any sense.

The checkbox can represent a mixed selection state, or tri-state (property: partiallySelected). The visual state depends on the value of the selected property.

Don't
Checkbox text - Don't format the checkbox incorrectly
Checkbox text - Don't format the checkbox incorrectly
Checkbox interaction value states
Checkbox interaction value states

Resources

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

Elements and Controls

Implementation

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:

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
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 feature on a tablet
Tabular autocomplete suggestion with sticky header
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
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
Input type text – Keyboard layout on a smartphone

Number

Input type number – Keyboard layout on a smartphone
Input type number – Keyboard layout on a smartphone

Email

Input type email – Keyboard layout on a smartphone
Input type email – Keyboard layout on a smartphone

URL

Input type URL – Keyboard layout on a smartphone
Input type URL – Keyboard layout on a smartphone

Telephone Number

Input type telephone number – Keyboard layout on a smartphone
Input type telephone number – Keyboard layout on a smartphone

Password

Input type password – Keyboard layout on a smartphone
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
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:

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

  1. Error
  2. Warning
  3. Success (no message is available for this state)
  4. Information

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

Input field in semantic colors with value state message below
Input field in semantic colors with value state message below

The value state message can be either a plain text or a formatted text.

Enabled, Read-only and Disabled states

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

  1. Enabled: This is the default setting.
  2. Read-only: The input field isn’t shown, just the value. This is used in display-only forms.
  3. 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 - Enabled
Input field - Read only
Input field - Read only
Input field - Disabled
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
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
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
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.

Alignment

The alignment rules are the same for display mode and edit mode.

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. To give a better indication of the type of data that can be selected, you can exchange the value help icon (property: valueHelpIconSrc). Once the value help option is enabled, the click event can be registered and one of the following displayed:

Warning
Don’t use the “value help only” option (property: valueHelpOnly). This can result in inconsistencies for screen reader users.
Input field with value help
Input field with value help
Custom value help icon
Custom value help icon

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. By default, the width of the suggestion box is the same as the width of the input field. You can change it with the maxSuggestionWidth property.
Note: The maximum width of the suggestion box is always slightly smaller than the width of the screen or browser window (with 1 rem of free space on the left and right sides), regardless of the value you provide for maxSuggestionWidth.

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. 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. 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 suggestionItemssap.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
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 suggestionItemssap.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
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. If there are too many columns for the available space, the width of the columns shrinks. Alternatively, you can enable the responsive behavior of the table (property: enableTableAutoPopinMode).

To use the tabular suggestion feature, use the suggestionColumns aggregation to define the columns and the correct responsive behavior for the pop-in content. 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:

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, suggestion box wider than the input field
Tabular autocomplete, suggestion box wider than the input field

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 suggestions
Input with grouped tabular suggestions
Input with grouped tabular suggestions

Clear

You can add a Clear icon to the input field (property: showClearIcon). It will appear as soon as the input field has a value. Clicking the Clear icon removes the value from the field. If used, make sure that the input field is wide enough to show the Clear icon in addition to the value.

'Clear' icon
'Clear' icon

Accessibility

  • The property ariaDescribedBy links the input field to other controls to provide additional information for assistive technologies, such as screen readers. If you use this property, we recommend linking either to on-screen controls that provide additional context or to an invisible text.

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

Alignment

The alignment rules are the same for display mode and edit mode.

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 fieldcombo boxmulti-combo box, and select controls.

Input field – 'New' action
Input field – 'New' action
Input field – 'Edit' 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

Implementation

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:

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
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 feature on a tablet
Tabular autocomplete suggestion with sticky header
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
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
Input type text – Keyboard layout on a smartphone

Number

Input type number – Keyboard layout on a smartphone
Input type number – Keyboard layout on a smartphone

Email

Input type email – Keyboard layout on a smartphone
Input type email – Keyboard layout on a smartphone

URL

Input type URL – Keyboard layout on a smartphone
Input type URL – Keyboard layout on a smartphone

Telephone Number

Input type telephone number – Keyboard layout on a smartphone
Input type telephone number – Keyboard layout on a smartphone

Password

Input type password – Keyboard layout on a smartphone
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
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:

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

  1. Error
  2. Warning
  3. Success (no message is available for this state)
  4. Information

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

Input field in semantic colors with value state message below
Input field in semantic colors with value state message below

The value state message can be either a plain text or a formatted text.

Enabled, Read-only and Disabled states

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

  1. Enabled: This is the default setting.
  2. Read-only: The input field is shown in a read-only state, with a grey background.
  3. 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 - Enabled
Input field - Read only
Input field - Read only
Input field - Disabled
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
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
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
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. To give a better indication of the type of data that can be selected, you can exchange the value help icon (property: valueHelpIconSrc). Once the value help option is enabled, the click event can be registered and one of the following displayed:

Warning
Don’t use the “value help only” option (property: valueHelpOnly). This can result in inconsistencies for screen reader users.
Input field with value help
Input field with value help
Custom value help icon
Custom value help icon

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. By default, the width of the suggestion box is the same as the width of the input field. You can change it with the maxSuggestionWidth property.
Note: The maximum width of the suggestion box is always slightly smaller than the width of the screen or browser window (with 1 rem of free space on the left and right sides), regardless of the value you provide for maxSuggestionWidth.

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. 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. 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 suggestionItemssap.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
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 suggestionItemssap.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
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. If there are too many columns for the available space, the width of the columns shrinks. Alternatively, you can enable the responsive behavior of the table (property: enableTableAutoPopinMode).

To use the tabular suggestion feature, use the suggestionColumns aggregation to define the columns and the correct responsive behavior for the pop-in content. 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:

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, suggestion box wider than the input field
Tabular autocomplete, suggestion box wider than the input field

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 suggestions
Input with grouped tabular suggestions
Input with grouped tabular suggestions

Clear

You can add a Clear icon to the input field (property: showClearIcon). It will appear as soon as the input field has a value. Clicking the Clear icon removes the value from the field. If used, make sure that the input field is wide enough to show the Clear icon in addition to the value.

'Clear' icon
'Clear' icon

Accessibility

  • The property ariaDescribedBy links the input field to other controls to provide additional information for assistive technologies, such as screen readers. If you use this property, we recommend linking either to on-screen controls that provide additional context or to an invisible text.

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

Alignment

The alignment rules are the same for display mode and edit mode.

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.

The value help dialog should tell users what values have already been entered into an 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 fieldcombo boxmulti-combo box, and select controls.

Input field – 'New' action
Input field – 'New' action
Input field – 'Edit' 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

Implementation

Value Help Dialog

Intro

The value help dialog is a UI pattern that helps the user search and select single and multiple values. The user can also define conditions.

The value help dialog is generally called from an input field or a multi-input field by clicking the selection icon (value help icon) of the input field.

Clicking the value help icon opens the value help dialog
Clicking the value help icon opens the value help dialog

Usage

Use the value help dialog if:

  • The user is searching within a dataset that contains more than 1,000 items.
  • The user needs to use different attributes to find an object (such as city, company name, and so on).
  • The user needs to define conditions, such as ranges and exclusions.

Do not use the value help dialog if:

  • There is a simpler control that fits the use case. Always start with the least complex control. For example, use the select control if the user needs to select only one item from a short list.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

The behavior of the value help dialog on a phone differs from its behavior on a tablet or desktop device. Both the navigation and the positioning of the selection area differ depending on the device.

Value help dialog - Sizes L and XL
Value help dialog - Sizes L and XL
Value help dialog - Size M
Value help dialog - Size M
Value help dialog - Size S
Value help dialog - Size S

Components

The value help dialog contains the following components:

1) Header
2) Icon tab bar / list control (phone)
3) Search template (optional)
4) Basic search
5) Go button
6) Result list
7) Selected items and conditions
8) Footer toolbar
9) Filters
10) Area for defining conditions, such as ranges and exclusions

Header (1)

The header bar contains the dialog title. See the Guidelines section below.

Icon Tab Bar / List Control (Phone) (2)

Depending on the device, the following controls are used to display the content of the value help dialog:

  • Smartphones: The start dialog provides a list (sap.m.List) with the standard list items (sap.m.StandardListItem), Search and Select, and Define Conditions to navigate between the different dialogs.
  • Tablet and desktop devices: The value help dialog contains an icon tab bar (sap.m.IconTabBar) to navigate between the Search and Select and the Define Conditions tab.
  • Both controls have a counter in the title that indicates the number of items/conditions selected.

Search Template (3)

Search templates allow the user to display different or additional fields in the filter area and result list. Depending on the use case, the user can switch between the different search templates in order to use different fields when searching. For example, the search template “Customer (by Company Code)” displays the additional field “Company Code” in the filter area and result list.

Basic Search (4)

The basic search finds all results that are somehow related to the input. For example, the search term “A” returns all the results containing the letter “A”.

Always offer the basic search in the value help dialog. Position the basic search to the right of the search template control. If there is no search template control, left-align the basic search.

Go Button (5)

The Go button triggers the search and filters the result list.

Result List (6)

  • The result list is populated on initial load by default.
  • If you transferred values from the input field to the basic search field of the value help dialog, the results are filtered accordingly. Only the entered (or modified) value is transferred to the basic search. Type-ahead suggestions are ignored. The search is triggered automatically when the dialog opens.
  • If available, display the ID and description of the business object in the first and second columns. Display additional information in the next columns.
  • We recommend a maximum of five columns in the result list.

Selected Items and Conditions (7)

The selected items and conditions are displayed in a tokenizer (see Token for more information). Each selected item or condition is displayed as one token.

There is no longer a visual difference between included and excluded items and conditions. They are now differentiated using operators (see Using the Filters).

Footer Toolbar (8)

The footer bar offers the OK and Cancel buttons.

Filters (9)

The filter area offers a filter field for each column in the result list. In some cases, there can be specific filter fields that do not have a corresponding column on the UI. These fields typically come from the back-end service. Initially, the filter area is hidden.

Value help dialog - Filters
Value help dialog - Filters

For the basic search with filters, the filter bar (sap.ui.comp.filterbar.FilterBar) is implemented in advanced mode. Advanced mode differs from the basic mode in the following ways:

  • There is no Filters link or a dialog to make additional filter fields visible. All filter fields are added automatically to the filter area.
  • There is a toggle button to show and hide the filters.
  • In each of the filter fields, users can use operators like “between” or “lower than” to define conditions.

Always hide the filter area in the value help dialog by default. Only show the filter area by default if the basic search can’t be provided.

Note that the value help icon of the Product ID field in the current value help dialog will open only the Define Conditions screen. The full value help dialog is not shown in order to prevent endless loops. For example, the value help icon of the Product Name or Category field in the value help for a Product field will navigate directly to the Define Conditions: Product screen.


Using the Filters

Users can enter operators (such as “=“) to define the conditions directly within the field without opening the Define Conditions tab.


Operator Input Notation Example
between valuevalue 000100
equal to =value =0001
contains *value* *1*
starts with value* 001*
ends with *value *5
less than <value <100
less than or equal to <=value <=200
greater than >value >0300
greater than or equal to >=value >=0500
not between !(valuevalue) !(000100)
not equal to !(=value)  !(=0)
does not contain !(*value*)  !(*1*)
does not start with !(value*)  !(001*)
does not end with !(*value)  !(*5)
not less than !(<value) !(<100)
not less than or equal to !(<=value) !(<=200)
not greater than !(>value)  !(>0300)
not greater than or equal to !(>=value)  !(>=0500)
empty <empty>   <empty>
not empty !(<empty>)    !(<empty>)

Note:

Depending on the underlying field, the operators may be labeled differently in the Define Conditions area. This doesn’t affect the input notation, which is based on the operator logic and remains constant.

Example: Operators for Date Fields

Operator Label Input Notation
before <value
before or on <=value
after >value
after or on >=value

 


Users must use the following notation to get results:

Using an operator to filter the result list
Using an operator to filter the result list

Area for Defining Conditions (10)

In the Define Conditions tab, you can use the following operators to define single and multiple conditions:

  • between
  • equal to
  • contains
  • starts with
  • ends with
  • less than
  • less than or equal to
  • greater than
  • greater than or equal to
  • empty
  • not between
  • not equal to
  • does not contains
  • does not start with
  • does not end with
  • not less than
  • not less than or equal to
  • not greater than
  • not greater than or equal to
  • not empty

For convenience, the operators are grouped into two categories: Include and Exclude.

For Boolean attributes, where only two values are available, the operator dropdown in the condition panel is disabled. Users can pick one of the values from the combo box.

You can also use a combo box if the possible values for a condition are fixed. Users can then choose the value they need from the list.

Each condition is displayed as a token in the Selected Items and Conditions tokenizer.

Information
The operator dropdown list may not contain all the operators listed above. The type of field value determines which operators are available.

The type of field value also determines how the operators are labeled. For example, if the field is a date field, the operator labels “less than” and “greater than” change to “before” and “after”.

Developer Hint
For information on how to manage white space characters (blanks) when users copy and paste text into input controls, see Removing Leading and Trailing White Space.
'Define Conditions' - List of operators
'Define Conditions' - List of operators
Defining a condition for a Boolean attribute
Defining a condition for a Boolean attribute

Behavior and Interaction

Basic Search and Filters

  • The basic search (mandatory) and filters (optional) are triggered by clicking the Go button. The search results are shown in the result list.
  • If data was already entered in input field from which the user triggered the value help, this data is transferred to the basic search and the results are then filtered accordingly.
  • The basic search performs a search across all fields that are displayed in the filter area and the result list.

Selecting Items and Defining Conditions

Depending on your use case, the value help dialog can offer different selection options:

  • Select a single item
  • Define a single condition
  • Select multiple items
  • Define multiple conditions
  • Select multiple items and define multiple conditions

Users open the value help dialog by clicking the value help icon in the input field. The next steps depend on the use case and form factor (smartphone or desktop/tablet).

The different use cases are described in the sections below.

Select a Single Item (Smartphone)

Tapping the value help icon opens the dialog. As soon as an item is selected, the value help dialog closes automatically.

Single item selection on a smartphone
Single item selection on a smartphone

Select a Single Item (Desktop/Tablet)

Clicking the value help icon opens the value help dialog for single selection. The icon tab bar and the Selected Items and Conditions are hidden. As soon as an item is selected, the value help dialog closes automatically.

Single item selection on a desktop/tablet device
Single item selection on a desktop/tablet device

Define a Single Condition (Smartphone)

Tapping the value help icon opens the Define Condition tab. Users define a condition by choosing the relevant operator and entering the value or values in the corresponding input field(s).

In this example, we have defined a range.

Defining a single condition on a smartphone
Defining a single condition on a smartphone

Define a Single Condition (Desktop/Tablet)

Clicking the value help icon opens the Define Condition tab. Users define a condition by choosing the relevant operator and entering the value or values in the corresponding input field(s).

In this example, we have defined a range.

Defining a single condition (desktop/tablet)
Defining a single condition (desktop/tablet)

Select Multiple Items and Define Multiple Conditions (Smartphone)

Tapping the value help icon displays the start dialog.

  • The Search and Select tab is used to select multiple items.
  • The Define Conditions tab is used to define multiple conditions.
  • The counters in the titles of both tabs represent the number of selected items/defined conditions.

All selected items and conditions are added as tokens to the Selected Items and Conditions (n) field at the bottom of the start dialog. The counter n indicates the combined number of items selected and conditions defined.

Start dialog
Start dialog
Selecting multiple items on a smartphone
Selecting multiple items on a smartphone
Defining multiple conditions (smartphone)
Defining multiple conditions (smartphone)
Filters on a smartphone
Filters on a smartphone

Select Multiple Items and Define Multiple Conditions (Desktop/Tablet)

Clicking the value help icon displays the icon tab bar with the Search and Select and Define Conditions tabs.

  • The Search and Select tab is used to select multiple items
  • The Define Conditions tab is used to define multiple conditions.

All selected items and conditions are added as tokens to the Selected Items and Conditions (n) field at the bottom of the dialog. The counter n indicates the combined number of items selected and conditions defined.

Selecting multiple items and conditions on a desktop
Selecting multiple items and conditions on a desktop
Selecting multiple items and conditions on a desktop
Selecting multiple items and conditions on a desktop

Define Multiple Conditions (Smartphone)

Tapping the value help icon opens the start dialog with the Define Conditions tab.

The selected values are added as tokens to the Selected Conditions at the bottom of the start dialog.

Start dialog
Start dialog
Defining multiple conditions on a smartphone
Defining multiple conditions on a smartphone

Define Multiple Conditions (Desktop/Tablet)

Clicking the value help icon opens the Define Conditions tab.

The selected values are added as tokens to the Selected Conditions at the bottom of the start dialog.

Defining multiple conditions on a desktop
Defining multiple conditions on a desktop

Copying and Pasting Multiple Values

The area for defining conditions allows the user to enter multiple values at once (copied from the clipboard).

Users can paste more than one value into the value input field. In this case, the condition row repeats with the previously selected condition and shows one value per row.

If there is no vertical space for the conditions, vertical scrolling is added to the top of the dialog.

Copying and pasting multiple values
Copying and pasting multiple values

Guidelines

Dialog Title

The dialog title differs depending on the device and whether multiple or single selection is used.

For smartphones:

  • Start dialog: [Object] (for example, Company)
  • Search and Select Dialog: Search and Select
  • Filters dialog: Show Filters
  • Define single condition: Define Condition
  • Define multiple conditions: Define Conditions

For tablet and desktop devices:

  • Selection of multiple items combined with selection of multiple conditions: [Object] (for example, Company)
  • Single item selection: Select: [Object] (for example, Select: Company)
  • Define single condition: Define Condition: [Object] (for example, Define Condition: Company)
  • Define multiple conditions: Define Conditions: [Object] (for example, Define Conditions: Company)

Filtering

If necessary, also provide value help for fields offered in the filters. However, do not provide the full value help dialog for the ID and description fields of the business object that is being selected. For these two fields, make sure that the value help icon opens only the Define Conditions screen.

For example, in a value help dialog for selecting the customer, do not offer full value help for the Customer ID and Customer Name fields. Instead, try to use the value help in combination with a helpful suggestion.

Constant Parameters

You can use constant parameters to pre-filter suggestion lists, dropdowns, and the value help results list. Users can’t change these parameters.

Do not show parameters with constant values as filterable fields in the filter bar of the value help dialog or in the result table columns. Constant values should not be visible to users in any way.

Related Links

Elements and Controls

Implementation

P13n Dialog

The P13n dialog control tabs allow users to personalize table and smart chart attributes.

Table Personalization Tabs

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

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

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

Smart Chart Personalization Tabs

In addition to the Sort and Filter tabs, the P13n dialog for smart charts can include the Chart tab to allow users to set the visibility of chart dimensions and measures.

The P13n dialog is opened using the corresponding buttons on the right-hand side of the table or chart toolbar, as shown below.

Usage

Use the P13n dialog if:

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

Do not use the P13n dialog if:

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

Responsiveness

The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), it shows as a centered dialog. For size S (smartphones), it displays as a full screen dialog.

Size S – Columns
Size S – Columns
Size M
Size M
Size L
Size L

Components

The P13n dialog can include the following tabs, separately or combined, as required by the use case:

  • Sort
  • Filter
  • Columns (available only for tables)
  • Group (available only for tables)
  • Chart (available only for the Smart Chart)

App developers can add more tabs manually.

Behavior and Interaction

Sort

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

Each entry has two input fields:

  • One for choosing the sort column in a table or the sort dimension or measure in a smart chart
  • The second for choosing the sort order.

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

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

Information

  • The new P13n panels from the SmartTable (ColumnsSortGroup) are now available for freestyle application development.
  • Using the sort feature for column headers replaces ALL sort options in the dialog!

Sort settings in the P13n dialog
Sort settings in the P13n dialog

Filter

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

Once a filter criterion is entered, a new line appears for entering another one. Users can remove filters by clicking the   (Remove Filter) icon at the end of each filter item.

Filter Criterion

In the first input field, the user selects the column (for tables) or the dimension/measure (for charts) to be filtered. Any column or dimension/measure can be selected, including columns and dimensions/measures that are not currently visible.

Define Conditions

The second field is an input field which calls a Value Help Dialog when the user clicks the selection icon (value help icon) in the input field.

The first input field in the value help dialog contains the operator that is applied to the filter value (such as greater than or not before).

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

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

Available operators:

String (Text)

  • between
  • contains
  • equal to
  • begins with
  • ends with
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Number

  • between
  • equal to
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Date

  • between
  • equal to
  • after
  • on or after
  • before
  • before or on

Boolean (true/false)

  • equal to

Value

The second field in the value help dialog contains the value by which the selected column is filtered. The kind of input field that is provided depends on the data type of the selected column and the selected operator. For example, the value field for fixed or Boolean values could be a dropdown list, an input field with suggestions, or a date picker. You can also offer two or even more fields if the use case requires it.

The above mentioned guidance for filtering is applied to both the table and chart personalization.

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

Columns

The Columns tab allows users to change the visible table columns and the order in which they are displayed.

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

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

Show/Hide

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

Reorder

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

Search

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

Information
The new P13n panels from the SmartTable (ColumnsSortGroup) are now available for freestyle application development.
Column settings in the P13n dialog
Column settings in the P13n dialog

Group

The Group tab allows users to group the table data.

In the select control, they can select a grouping criterion from a list of all available columns.

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

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

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

Information
The new P13n panels from the SmartTable (ColumnsSortGroup) are now available for freestyle application development.
Warning
Only columns marked as visible on the Columns tab can be used for grouping!
Group tab in the P13n dialog
Group tab in the P13n dialog

Chart

The Chart tab allows users to set the visibility of chart dimensions and measures and to change the order in which they are displayed.

Users can add dimensions and measures with the select control or remove them by clicking the  (Remove dimension/measure) icon at the end of each chart item.

They can enter multiple dimensions and measures. Once a dimension or measure is entered, a new line appears for entering another one.

The order of the entered dimensions and measures reflects the order in which they are applied to the chart.

Dimensions

Each entry has two select controls: one for choosing the dimension, and one for choosing the layout option. The dialog is adapted to the currently selected chart type and shows layout options that work on the selected chart type.

Measures

In the select control, the user can select a needed measure from a list of all available measures.

Reorder

To change the order of the dimensions and measures, users focus on the list item and use the buttons on the right-hand side of the table toolbar to move it up or down or by dragging the dimension/measure to the desired location.

Warning
Users can select or change a chart type via the Smart Charts toolbar!
Chart settings in the P13n dialog
Chart settings in the P13n dialog

Resources

Elements and Controls

Implementation

Table Personalization Dialog

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

Usage

Use the table personalization dialog if:

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

Do not use the table personalization dialog if:

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

For larger tables you can use the P13n dialog instead.

Responsiveness

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

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

Smartphone - Size S
Smartphone - Size S
Tablet - Size M
Tablet - Size M
Desktop - Size L/XL
Desktop - Size L/XL

Layout

Position on the Screen

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

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

Layout of the Dialog

The table personalization dialog comprises the following five areas:

(1) Header

(2) Toolbar

(3) List Header

(4) Column list

(5) Footer toolbar

Table personalization dialog – Overview
Table personalization dialog – Overview

Components

The table personalization dialog contains the following sections:

Dialog Header

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

Dialog header
Dialog header

Toolbar

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

Toolbar
Toolbar

List Header

The list header displays the Select All checkbox for selecting all columns.

List header
List header

Column list

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

Column list
Column list

Footer toolbar

The footer toolbar displays an OK and a Cancel button.

Footer toolbar
Footer toolbar

Behavior and Interaction

The table personalization dialog is resizable.

Open the Dialog

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

Table with settings button
Table with settings button
Table personalization dialog opened
Table personalization dialog opened

Show or Hide Columns

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

The column is hidden in the table
The column is hidden in the table
The column is visible in the table
The column is visible in the table

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

Show all
Show all
Hide all
Hide all

Move Columns

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

To change the order, click an item (not on the check box, but on the rest of the line), and click the button: Items on top are farthest to the left in the table, items on bottom are farthest to the right.

Move buttons
Move buttons
The column 'Supplier' will be moved. It is not checked, though, therefore the result of moving this column will not be visible in the table.
The column 'Supplier' will be moved. It is not checked, though, therefore the result of moving this column will not be visible in the table.

Search/Filter Columns

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

Search field
Search field

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

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

The list then shows all columns again.

Search while you type
Search while you type

Reset Personalization

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

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

Reset button
Reset button

Confirm/Cancel Changes

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

The Cancel button closes the dialog without applying the changes.

OK and Cancel buttons
OK and Cancel buttons

Resources

Elements and Controls

Implementation

P13n Dialog

The P13n dialog control tabs allow users to personalize table and smart chart attributes.

Table Personalization Tabs

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

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

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

Smart Chart Personalization Tabs

In addition to the Sort and Filter tabs, the P13n dialog for smart charts can include the Chart tab to allow users to set the visibility of chart dimensions and measures.

The P13n dialog is opened using the corresponding buttons on the right-hand side of the table or chart toolbar, as shown below.

Usage

Use the P13n dialog if:

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

Do not use the P13n dialog if:

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

Responsiveness

The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), it shows as a centered dialog. For size S (smartphones), it displays as a full screen dialog.

Size S – Columns
Size S – Columns
Size M
Size M
Size L
Size L

Components

The P13n dialog can include the following tabs, separately or combined, as required by the use case:

  • Sort
  • Filter
  • Columns (available only for tables)
  • Group (available only for tables)
  • Chart (available only for the Smart Chart)

App developers can add more tabs manually.

Behavior and Interaction

Sort

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

Each entry has two input fields:

  • One for choosing the sort column in a table or the sort dimension or measure in a smart chart
  • The second for choosing the sort order.

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

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

Information

  • The new P13n panels from the SmartTable (ColumnsSortGroup) are now available for freestyle application development.
  • Using the sort feature for column headers replaces ALL sort options in the dialog!

Sort settings in the P13n dialog
Sort settings in the P13n dialog

Filter

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

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

Column

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

Operator

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

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

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

Available operators:

String (Text)

  • between
  • contains
  • equal to
  • begins with
  • ends with
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Number

  • between
  • equal to
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Date

  • between
  • equal to
  • after
  • on or after
  • before
  • before or on

Boolean (true/false)

  • equal to

Value

The last field contains the value by which the selected column is filtered. The kind of input field that is provided depends on the data type of the selected column and the selected operator. For example, the value field for fixed or Boolean values could be a dropdown list, an input field with suggestions, or a date picker. You can also offer two or even more fields if the use case requires it.

The above mentioned guidance for filtering is also applied to the chart personalization.

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

Columns

The Columns tab allows users to change the visible table columns and the order in which they are displayed.

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

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

Show/Hide

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

Reorder

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

Search

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

Information
The new P13n panels from the SmartTable (ColumnsSortGroup) are now available for freestyle application development.
Column settings in the P13n dialog
Column settings in the P13n dialog

Group

The Group tab allows users to group the table data.

In the select control, they can select a grouping criterion from a list of all available columns.

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

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

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

Information
The new P13n panels from the SmartTable (ColumnsSortGroup) are now available for freestyle application development.
Warning
Only columns marked as visible on the Columns tab can be used for grouping!
Group tab in the P13n dialog
Group tab in the P13n dialog

Chart

The Chart tab allows users to set the visibility of chart dimensions and measures and to change the order in which they are displayed.

Users can add dimensions and measures with the select control or remove them by clicking the  (Remove dimension/measure) icon at the end of each chart item.

They can enter multiple dimensions and measures. Once a dimension or measure is entered, a new line appears for entering another one.

The order of the entered dimensions and measures reflects the order in which they are applied to the chart.

Dimensions

Each entry has two select controls: one for choosing the dimension, and one for choosing the layout option. The dialog is adapted to the currently selected chart type and shows layout options that work on the selected chart type.

Measures

In the select control, the user can select a needed measure from a list of all available measures.

Reorder

To change the order of the dimensions and measures, users focus on the list item and use the buttons on the right-hand side of the table toolbar to move it up or down or by dragging the dimension/measure to the desired location.

Warning
Users can select or change a chart type via the Smart Charts toolbar!
Chart settings in the P13n dialog
Chart settings in the P13n dialog

Resources

Elements and Controls

Implementation

P13n Dialog

The P13n dialog control tabs allow users to personalize table and smart chart attributes.

Table Personalization Tabs

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

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

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

Smart Chart Personalization Tabs

In addition to the Sort and Filter tabs, the P13n dialog for smart charts can include the Chart tab to allow users to set the visibility of chart dimensions and measures.

The P13n dialog is opened using the corresponding buttons on the right-hand side of the table or chart toolbar, as shown below.

Usage

Use the P13n dialog if:

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

Do not use the P13n dialog if:

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

Responsiveness

The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), it shows as a centered dialog. For size S (smartphones), it displays as a full screen dialog.

Size S – Columns
Size S – Columns
Size M
Size M
Size L
Size L

Components

The P13n dialog can include the following tabs, separately or combined, as required by the use case:

  • Sort
  • Filter
  • Columns (available only for tables)
  • Group (available only for tables)
  • Chart (available only for the Smart Chart)

App developers can add more tabs manually.

Behavior and Interaction

Sort

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

Each entry has two input fields:

  • One for choosing the sort column in a table or the sort dimension or measure in a smart chart
  • The second for choosing the sort order.

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

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

Information

  • The new P13n panels from the SmartTable (ColumnsSortGroup) are now available for freestyle application development.
  • Using the sort feature for column headers replaces ALL sort options in the dialog!

Sort settings in the P13n dialog
Sort settings in the P13n dialog

Filter

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

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

Column

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

Operator

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

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

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

Available operators:

String (Text)

  • between
  • contains
  • equal to
  • begins with
  • ends with
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Number

  • between
  • equal to
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Date

  • between
  • equal to
  • after
  • on or after
  • before
  • before or on

Boolean (true/false)

  • equal to

Value

The second field in the value help dialog contains the value by which the selected column is filtered. The kind of input field that is provided depends on the data type of the selected column and the selected operator. For example, the value field for fixed or Boolean values could be a dropdown list, an input field with suggestions, or a date picker. You can also offer two or even more fields if the use case requires it.

The above mentioned guidance for filtering is also applied to both the table and chart personalization.

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

Columns

The Columns tab allows users to change the visible table columns and the order in which they are displayed.

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

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

Show/Hide

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

Reorder

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

Search

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

Information
The new P13n panels from the SmartTable (ColumnsSortGroup) are now available for freestyle application development.
Column settings in the P13n dialog
Column settings in the P13n dialog

Group

The Group tab allows users to group the table data.

In the select control, they can select a grouping criterion from a list of all available columns.

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

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

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

Information
The new P13n panels from the SmartTable (ColumnsSortGroup) are now available for freestyle application development.
Warning
Only columns marked as visible on the Columns tab can be used for grouping!
Group tab in the P13n dialog
Group tab in the P13n dialog

Chart

The Chart tab allows users to set the visibility of chart dimensions and measures and to change the order in which they are displayed.

Users can add dimensions and measures with the select control or remove them by clicking the  (Remove dimension/measure) icon at the end of each chart item.

They can enter multiple dimensions and measures. Once a dimension or measure is entered, a new line appears for entering another one.

The order of the entered dimensions and measures reflects the order in which they are applied to the chart.

Dimensions

Each entry has two select controls: one for choosing the dimension, and one for choosing the layout option. The dialog is adapted to the currently selected chart type and shows layout options that work on the selected chart type.

Measures

In the select control, the user can select a needed measure from a list of all available measures.

Reorder

To change the order of the dimensions and measures, users focus on the list item and use the buttons on the right-hand side of the table toolbar to move it up or down or by dragging the dimension/measure to the desired location.

Warning
Users can select or change a chart type via the Smart Charts toolbar!
Chart settings in the P13n dialog
Chart settings in the P13n dialog

Resources

Elements and Controls

Implementation

P13n Dialog

The P13n dialog control tabs allow users to personalize table and smart chart attributes.

Table Personalization Tabs

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

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

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

Smart Chart Personalization Tabs

In addition to the Sort and Filter tabs, the P13n dialog for smart charts can include the Chart tab to allow users to set the visibility of chart dimensions and measures.

The P13n dialog is opened using the corresponding buttons on the right-hand side of the table or chart toolbar, as shown below.

Usage

Use the P13n dialog if:

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

Do not use the P13n dialog if:

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

Responsiveness

The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), it shows as a centered dialog. For size S (smartphones), it displays as a full screen dialog.

Size S – Columns
Size S – Columns
Size M
Size M
Size L
Size L

Components

The P13n dialog can include the following tabs, separately or combined, as required by the use case:

  • Sort
  • Filter
  • Columns (available only for tables)
  • Group (available only for tables)
  • Chart (available only for the Smart Chart)

App developers can add more tabs manually.

Behavior and Interaction

Sort

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

Each entry has two input fields:

  • One for choosing the sort column in a table or the sort dimension or measure in a smart chart
  • The second for choosing the sort order.

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

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

Information

  • The new P13n panels from the SmartTable (ColumnsSortGroup) are now available for freestyle application development.
  • Using the sort feature for column headers replaces ALL sort options in the dialog!

Sort settings in the P13n dialog
Sort settings in the P13n dialog

Filter

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

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

Column

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

Operator

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

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

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

Available operators:

String (Text)

  • between
  • contains
  • equal to
  • begins with
  • ends with
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Number

  • between
  • equal to
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Date

  • between
  • equal to
  • after
  • on or after
  • before
  • before or on

Boolean (true/false)

  • equal to

Value

The second field in the value help dialog contains the value by which the selected column is filtered. The kind of input field that is provided depends on the data type of the selected column and the selected operator. For example, the value field for fixed or Boolean values could be a dropdown list, an input field with suggestions, or a date picker. You can also offer two or even more fields if the use case requires it.

The above mentioned guidance for filtering is also applied to both the table and chart personalization.

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

Columns

The Columns tab allows users to change the visible table columns and the order in which they are displayed.

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

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

Show/Hide

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

Reorder

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

Search

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

Information
The new P13n panels from the SmartTable (ColumnsSortGroup) are now available for freestyle application development.
Column settings in the P13n dialog
Column settings in the P13n dialog

Group

The Group tab allows users to group the table data.

In the select control, they can select a grouping criterion from a list of all available columns.

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

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

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

Information
The new P13n panels from the SmartTable (ColumnsSortGroup) are now available for freestyle application development.
Warning
Only columns marked as visible on the Columns tab can be used for grouping!
Group tab in the P13n dialog
Group tab in the P13n dialog

Chart

The Chart tab allows users to set the visibility of chart dimensions and measures and to change the order in which they are displayed.

Users can add dimensions and measures with the select control or remove them by clicking the  (Remove dimension/measure) icon at the end of each chart item.

They can enter multiple dimensions and measures. Once a dimension or measure is entered, a new line appears for entering another one.

The order of the entered dimensions and measures reflects the order in which they are applied to the chart.

Dimensions

Each entry has two select controls: one for choosing the dimension, and one for choosing the layout option. The dialog is adapted to the currently selected chart type and shows layout options that work on the selected chart type.

Measures

In the select control, the user can select a needed measure from a list of all available measures.

Reorder

To change the order of the dimensions and measures, users focus on the list item and use the buttons on the right-hand side of the table toolbar to move it up or down or by dragging the dimension/measure to the desired location.

Warning
Users can select or change a chart type via the Smart Charts toolbar!
Chart settings in the P13n dialog
Chart settings in the P13n dialog

Resources

Elements and Controls

Implementation

P13n Dialog

Warning
The sap.m.P13nDialog control has been deprecated. See the new control sap.m.p13n.Popup.

Intro

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

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

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

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

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

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

Usage

Use the P13n dialog if:

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

Do not use the P13n dialog if:

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

Responsiveness

The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), it shows as a centered dialog. For size S (smartphones), it displays as a full screen dialog.

Size S – Columns
Size S – Columns
Size M
Size M
Size L
Size L

Components

The P13n dialog consists of four different tabs that can be used separately or combined, as required by the use case:

  • Sort
  • Filter
  • Group
  • Columns

App developers can add more tabs manually.

Behavior and Interaction

Columns

The Columns tab allows users to change the visible table columns and the order in which they are displayed.

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

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

Show/Hide

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

Reorder

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

Search

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

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

Sort

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

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

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

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

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

Filter

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

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

Column

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

Operator

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

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

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

Available operators:

String (Text)

  • between
  • contains
  • equal to
  • begins with
  • ends with
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Number

  • between
  • equal to
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Date

  • between
  • equal to
  • after
  • on or after
  • before
  • before or on

Boolean (true/false)

  • equal to

Value

The last field contains the value by which the selected column is filtered. The kind of input field that is provided depends on the data type of the selected column and the selected operator. For example, the value field for fixed or Boolean values could be a dropdown list, an input field with suggestions, or a date picker. You can also offer two or even more fields if the use case requires it.

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

Group

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

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

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

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

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

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

Resources

Elements and Controls

Implementation

Value Help Dialog

Intro

The value help dialog is a UI pattern that helps the user search and select single and multiple values. The user can also define conditions.

The value help dialog is generally called from an input field or a multi-input field by clicking the selection icon (value help icon) of the input field.

Clicking the value help icon opens the value help dialog
Clicking the value help icon opens the value help dialog

Usage

Use the value help dialog if:

  • The user is searching within a dataset that contains more than 1,000 items.
  • The user needs to use different attributes to find an object (such as city, company name, and so on).
  • The user needs to define conditions, such as ranges and exclusions.

Do not use the value help dialog if:

  • There is a simpler control that fits the use case. Always start with the least complex control. For example, use the select control if the user needs to select only one item from a short list.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

The behavior of the value help dialog on a phone differs from its behavior on a tablet or desktop device. Both the navigation and the positioning of the selection area differ depending on the device.

Value help dialog - Sizes L and XL
Value help dialog - Sizes L and XL
Value help dialog - Size M
Value help dialog - Size M
Value help dialog - Size S
Value help dialog - Size S

Components

The value help dialog contains the following components:

1) Header
2) Icon tab bar / list control (phone)
3) Search template (optional)
4) Basic search
5) Go button
6) Result list
7) Selected items and conditions
8) Footer toolbar
9) Filters
10) Area for defining conditions, such as ranges and exclusions

Header (1)

The header bar contains the dialog title. See the Guidelines section below.

Icon Tab Bar / List Control (Phone) (2)

Depending on the device, the following controls are used to display the content of the value help dialog:

  • Smartphones: The start dialog provides a list (sap.m.List) with the standard list items (sap.m.StandardListItem), Search and Select, and Define Conditions to navigate between the different dialogs.
  • Tablet and desktop devices: The value help dialog contains an icon tab bar (sap.m.IconTabBar) to navigate between the Search and Select and the Define Conditions tab.
  • Both controls have a counter in the title that indicates the number of items/conditions selected.

Search Template (3)

Search templates allow the user to display different or additional fields in the filter area and result list. Depending on the use case, the user can switch between the different search templates in order to use different fields when searching. For example, the search template “Customer (by Company Code)” displays the additional field “Company Code” in the filter area and result list.

Basic Search (4)

The basic search finds all results that are somehow related to the input. For example, the search term “A” returns all the results containing the letter “A”.

Always offer the basic search in the value help dialog. Position the basic search to the right of the search template control. If there is no search template control, left-align the basic search.

Go Button (5)

The Go button triggers the search and filters the result list.

Result List (6)

  • The result list is populated on initial load by default.
  • If you transferred values from the input field to the basic search field of the value help dialog, the results are filtered accordingly. Only the entered (or modified) value is transferred to the basic search. Type-ahead suggestions are ignored. The search is triggered automatically when the dialog opens.
  • If available, display the ID and description of the business object in the first and second columns. Display additional information in the next columns.
  • We recommend a maximum of five columns in the result list.

Selected Items and Conditions (7)

The selected items and conditions are displayed in a tokenizer (see Token for more information). Each selected item or condition is displayed as one token.

There is no longer a visual difference between included and excluded items and conditions. They are now differentiated using operators (see Using the Filters).

Footer Toolbar (8)

The footer bar offers the OK and Cancel buttons.

Filters (9)

The filter area offers a filter field for each column in the result list. In some cases, there can be specific filter fields that do not have a corresponding column on the UI. These fields typically come from the back-end service. Initially, the filter area is hidden.

Value help dialog - Filters
Value help dialog - Filters

For the basic search with filters, the filter bar (sap.ui.comp.filterbar.FilterBar) is implemented in advanced mode. Advanced mode differs from the basic mode in the following ways:

  • There is no Filters link or a dialog to make additional filter fields visible. All filter fields are added automatically to the filter area.
  • There is a toggle button to show and hide the filters.
  • In each of the filter fields, users can use operators like “between” or “lower than” to define conditions.

Always hide the filter area in the value help dialog by default. Only show the filter area by default if the basic search can’t be provided.

Note that the value help icon of the Product ID field in the current value help dialog will open only the Define Conditions screen. The full value help dialog is not shown in order to prevent endless loops. For example, the value help icon of the Product Name or Category field in the value help for a Product field will navigate directly to the Define Conditions: Product screen.

Using the Filters

Users can enter operators (such as “=“) to define the conditions directly within the field without opening the Define Conditions tab.

Users must use the following notation to get results:

Operator Input Notation Example
between valuevalue 000100
equal to =value =0001
contains *value* *1*
starts with value* 001*
ends with *value *5
less than <value <100
less than or equal to <=value <=200
greater than >value >0300
greater than or equal to >=value >=0500
not between !(valuevalue) !(000100)
not equal to !(=value)  !(=0)
does not contain !(*value*)  !(*1*)
does not start with !(value*)  !(001*)
does not end with !(*value)  !(*5)
not less than !(<value) !(<100)
not less than or equal to !(<=value) !(<=200)
not greater than !(>value)  !(>0300)
not greater than or equal to !(>=value)  !(>=0500)
empty <empty>   <empty>
not empty !(<empty>)    !(<empty>)
Using an operator to filter the result list
Using an operator to filter the result list

Area for Defining Conditions (10)

In the Define Conditions tab, you can use the following operators to define single and multiple conditions:

  • between
  • equal to
  • contains
  • starts with
  • ends with
  • less than
  • less than or equal to
  • greater than
  • greater than or equal to
  • empty
  • not between
  • not equal to
  • does not contains
  • does not start with
  • does not end with
  • not less than
  • not less than or equal to
  • not greater than
  • not greater than or equal to
  • not empty

For convenience, the operators are grouped into two categories: Include and Exclude.

For Boolean attributes, where only two values are available, the operator drop-down in the condition panel is disabled. Users can pick one of the values from the combo box.

You can also use a combo box if the possible values for a condition are fixed. Users can then choose the value they need from the list.

Each condition is displayed as a token in the Selected Items and Conditions tokenizer.

Information
The operator dropdown list may not contain all the operators listed above. The type of field value determines which operators are available.
Developer Hint
For information on how to manage white space characters (blanks) when users copy and paste text into input controls, see Removing Leading and Trailing White Space.
'Define Conditions' - List of operators
'Define Conditions' - List of operators
Defining a condition for a Boolean attribute
Defining a condition for a Boolean attribute

Behavior and Interaction

Basic Search and Filters

  • The basic search (mandatory) and filters (optional) are triggered by clicking the Go button. The search results are shown in the result list.
  • If data was already entered in input field from which the user triggered the value help, this data is transferred to the basic search and the results are then filtered accordingly.
  • The basic search performs a search across all fields that are displayed in the filter area and the result list.

Selecting Items and Defining Conditions

Depending on your use case, the value help dialog can offer different selection options:

  • Select a single item
  • Define a single condition
  • Select multiple items
  • Define multiple conditions
  • Select multiple items and define multiple conditions

Users open the value help dialog by clicking the value help icon in the input field. The next steps depend on the use case and form factor (smartphone or desktop/tablet).

The different use cases are described in the sections below.

Select a Single Item (Smartphone)

Tapping the value help icon opens the dialog. As soon as an item is selected, the value help dialog closes automatically.

Single item selection on a smartphone
Single item selection on a smartphone

Select a Single Item (Desktop/Tablet)

Clicking the value help icon opens the value help dialog for single selection. The icon tab bar and the Selected Items and Conditions are hidden. As soon as an item is selected, the value help dialog closes automatically.

Single item selection on a desktop/tablet device
Single item selection on a desktop/tablet device

Define a Single Condition (Smartphone)

Tapping the value help icon opens the Define Condition tab. Users define a condition by choosing the relevant operator and entering the value or values in the corresponding input field(s).

In this example, we have defined a range.

Defining a single condition on a smartphone
Defining a single condition on a smartphone

Define a Single Condition (Desktop/Tablet)

Clicking the value help icon opens the Define Condition tab. Users define a condition by choosing the relevant operator and entering the value or values in the corresponding input field(s).

In this example, we have defined a range.

Defining a single condition (desktop/tablet)
Defining a single condition (desktop/tablet)

Select Multiple Items and Define Multiple Conditions (Smartphone)

Tapping the value help icon displays the start dialog.

  • The Search and Select tab is used to select multiple items.
  • The Define Conditions tab is used to define multiple conditions.
  • The counters in the titles of both tabs represent the number of selected items/defined conditions.

All selected items and conditions are added as tokens to the Selected Items and Conditions (n) field at the bottom of the start dialog. The counter n indicates the combined number of items selected and conditions defined.

Start dialog
Start dialog
Selecting multiple items on a smartphone
Selecting multiple items on a smartphone
Defining multiple conditions (smartphone)
Defining multiple conditions (smartphone)
Filters on a smartphone
Filters on a smartphone

Select Multiple Items and Define Multiple Conditions (Desktop/Tablet)

Clicking the value help icon displays the icon tab bar with the Search and Select and Define Conditions tabs.

  • The Search and Select tab is used to select multiple items
  • The Define Conditions tab is used to define multiple conditions.

All selected items and conditions are added as tokens to the Selected Items and Conditions (n) field at the bottom of the dialog. The counter n indicates the combined number of items selected and conditions defined.

Selecting multiple items and conditions on a desktop
Selecting multiple items and conditions on a desktop
Selecting multiple items and conditions on a desktop
Selecting multiple items and conditions on a desktop

Define Multiple Conditions (Smartphone)

Tapping the value help icon opens the start dialog with the Define Conditions tab.

The selected values are added as tokens to the Selected Conditions at the bottom of the start dialog.

Start dialog
Start dialog
Defining multiple conditions on a smartphone
Defining multiple conditions on a smartphone

Define Multiple Conditions (Desktop/Tablet)

Clicking the value help icon opens the Define Conditions tab.

The selected values are added as tokens to the Selected Conditions at the bottom of the start dialog.

Defining multiple conditions on a desktop
Defining multiple conditions on a desktop

Copying and Pasting Multiple Values

The area for defining conditions allows the user to enter multiple values at once (copied from the clipboard).

Users can paste more than one value into the value input field. In this case, the condition row repeats with the previously selected condition and shows one value per row.

If there is no vertical space for the conditions, vertical scrolling is added to the top of the dialog.

Copying and pasting multiple values
Copying and pasting multiple values

Guidelines

Dialog Title

The dialog title differs depending on the device and whether multiple or single selection is used.

For smartphones:

  • Start dialog: [Object] (for example, Company)
  • Search and Select Dialog: Search and Select
  • Filters dialog: Show Filters
  • Define single condition: Define Condition
  • Define multiple conditions: Define Conditions

For tablet and desktop devices:

  • Selection of multiple items combined with selection of multiple conditions: [Object] (for example, Company)
  • Single item selection: Select: [Object] (for example, Select: Company)
  • Define single condition: Define Condition: [Object] (for example, Define Condition: Company)
  • Define multiple conditions: Define Conditions: [Object] (for example, Define Conditions: Company)

Filtering

If necessary, also provide value help for fields offered in the filters. However, do not provide the full value help dialog for the ID and description fields of the business object that is being selected. For these two fields, make sure that the value help icon opens only the Define Conditions screen.

For example, in a value help dialog for selecting the customer, do not offer full value help for the Customer ID and Customer Name fields. Instead, try to use the value help in combination with a helpful suggestion.

Constant Parameters

You can use constant parameters to pre-filter suggestion lists, drop-downs, and the value help results list. Users can’t change these parameters.

Do not show parameters with constant values as filterable fields in the filter bar of the value help dialog or in the result table columns. Constant values should not be visible to users in any way.

Related Links

Elements and Controls

Implementation

Date Range Selection

The control for selecting the date range is a single-field input control. Users can enter a localized date range using touch, mouse, or keyboard input, or by selecting a date range in the calendar. They can also navigate directly from one month or year to another.

Usage

Use the date range selection if:

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

Do not use the date range selection if:

  • You want to enter a date and a time. In this case, use the date picker or time picker instead.
  • The user’s primary goal is not to select ranges. If this is the case, use the simple date picker.
  • You want to let users choose from a flexible set of absolute and relative dates and date ranges. In this case, use the dynamic date range.

Responsiveness

The date range selection is fully responsive. It is smaller in compact mode and provides a touch-friendly size in cozy mode. For more information about cozy and compact modes, see the article on content density.

Date range selection (size S)
Date range selection (size S)
Date range selection (size L)
Date range selection (size L)

Components

The date range selection consists of two components:

  1. Date range input field
  2. Date range picker
The two clickable areas of the date range selection on all devices
The two clickable areas of the date range selection on all devices

Date Range Input Field

The user can type the date directly into the input field, or use the date picker. You can also show a prompt text in the field (property: placeholder). The system validates the date and gives the user feedback.

  1. Current day
  2. Currently selected date range

It is possible to add additional descriptive texts to the input field (a unit of measurement, for example) by using a new association in the sap.m.InputBase control called ariaDescribedByThe association is responsible for referencing the elements that describe the control.

The current day is December 5 and December 19–22 are selected
The current day is December 5 and December 19–22 are selected

Date Range Picker

With the date range picker, the user can see a day view, month view, or year view. The current day and the selected date are highlighted. The calendar week is also visible in the day view. The calendar closes when a final day is selected. The user can click the arrows to view the previous and next days, months, or years (depending on the current view).

The selected date is shown with a blue background. The current day is indicated with a purple border in the calendar.

1. Previous month

2. Quick month selection

3. Quick year selection

4. Next month

5. Day selection

Clickable areas of the date range selection
Clickable areas of the date range selection

Optionally, you can offer a footer with OK and Cancel buttons. This gives users an alternative way of confirming the selected date range.

Date range picker with 'OK' and 'Cancel'
Date range picker with 'OK' and 'Cancel'

Alternative triggers for the Date Range Selection

In addition to the date range input field, you can set one of the following to trigger the date range selection popover:

  • A button
  • A link
Button and link triggers for the date range selection popover
Button and link triggers for the date range selection popover

Behavior and Interaction

Selecting a Date Range

The users can type two dates into the date range input field or click the calendar icon to open the calendar and select a date. These two possibilities work for all devices – desktops, tablets, and smartphones.

Switch View

Users can click an arrow to shows the next or previous day, month, or year.

Navigating to the next month
Navigating to the next month

When they click the month the month picker is displayed.

Opening the month picker
Opening the month picker

In the month picker, after the users click a month to select it, the day picker is displayed with the focus on the last selected start date.

Navigation from the month picker to the date picker
Navigation from the month picker to the date picker

When the users click the current year, the year picker is displayed. After selecting a year, they navigate back to the day picker.

Opening the year picker
Opening the year picker

Selecting a Range

After the users select a start date, the dates that they hover over turn light blue to indicate they are selected for the range. When the users select an end date, the calendar closes. The range appears in the date input field.

Selecting the start date
Selecting the start date
Selecting the end date
Selecting the end date

Entering Single Dates

The date range selection also allows the users to input single dates. They can type one date into the input field, or select the same day as a start and end date in the calendar.

“Today” Button

You can offer a shortcut for navigating to the current date (sap.m.DateRangeSelection, property: showCurrentDateButton). This displays an additional Today icon button ( ) in the navigation part of the calendar.

When the user clicks the Today button, the system automatically makes the current date the starting date for the new date range.

If the user has already selected the first date in the date range and then clicks the Today button, the focus is set to the current date. The system cancels the previous selection and makes the current day the starting date for the new selection.

This feature is available for pickers that enable selection of individual days. For the others, the property has no effect.

Selecting current date with the 'Today' button
Selecting current date with the 'Today' button

Styles

Delimiter

The delimiter visualizes the start and end date. If no delimiter is given, the app uses the one defined for the used locale.

Placeholder

If no range is selected, show a placeholder text to indicate the correct format. If no placeholder is defined, the control shows the default locale placeholder format. You can define your own placeholder, but you must also take localized versions into account.

Date range selection with default placeholder
Date range selection with default placeholder

Validation

Use inline validation to give the user feedback, especially for errors and warnings. Possible validation states are warning, error, success, and information. The date range input field in question is highlighted by a frame in the corresponding color. If the focus is inside the field, an explanation is shown. Ensure that this explanation is as specific as possible.

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

Visible frame that shows an error when the field is out of focus
Visible frame that shows an error when the field is out of focus
Error state with meaningful text; the date range input field is focused
Error state with meaningful text; the date range input field is focused
Visible frame that shows a warning when the field is out of focus
Visible frame that shows a warning when the field is out of focus
Warning state with meaningful text; the date range input field is focused
Warning state with meaningful text; the date range input field is focused
Visible frame that shows that additional information is available
Visible frame that shows that additional information is available
Information state with additional information, such as a recommendation
Information state with additional information, such as a recommendation

Guidelines

Display Format

You can choose whether the displayed texts are to be shown in short, medium, or long format, or in another date format like dd–MM–yyyy. However, other date formats (besides short, medium, and long) should be used carefully due to local dependencies.

Long display format
Long display format
Medium display format
Medium display format
Short display format
Short display format

Input Types

The following input types are available. (Note: these examples show German date formats for January 14, 2014.)

  • Unicode CLDR short format: 14.01.14
  • Unicode CLDR medium format: 14.01.2014
  • ISO date format: 2014-01-14
  • ISO date format without delimiters: 20140114
  • Unicode CLDR short format without delimiters: 140114
  • Unicode CLDR medium format: 14012014

Date Formats

Long Date Format

Use the long date format for a list in a list-detail layout / 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 a list in a list-detail layout / 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 a list in a list-detail layout / 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.

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

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

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

Resources

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

Elements and Controls

Implementation

Planning Calendar

The planning calendar allows users to see different appointments at the same time and to create new appointments. It allows the user to display appointments for several objects, such as a team calendar, and compare them to each other.

Usage

Use the planning calendar if:

  • You want to compare objects of the same type with each other over a period of time.
  • You require responsive behavior.
  • You have less than 100 lines in the calendar.

Do not use the planning calendar if:

  • You want to show a calendar for one object and a detailed overview of appointments over a long time interval.
  • You want to show a complex or graphical representation. In this case, please use the Gantt chart.
  • You have more than 100 lines in the calendar. In this case, please use the Gantt chart.

Responsiveness

In size S, the control provides pop-in behavior, which allows the user to see as many appointments as possible and to connect them with the corresponding object. If the toolbar contains too many actions for the space available, the overflow icon appears.

The interval section displaying the hours, days, and months is responsive and shows 12 values in size L, 8 values in size M, and 6 values in size S. You can override this behavior, but you should then check that the responsiveness is still working.

Planning calendar - Size L
Planning calendar - Size L
Planning calendar - Size M
Planning calendar - Size M
Planning calendar - Size S
Planning calendar - Size S

Types

You can define what size of interval the calendar should show, and whether multi selection should be possible. Additionally, the row header and the interval appointments are optional.

The control allows multi-select mode to be shown for the list items. This can be used, for example, to delete multiple objects from the view.

An app development team must decide whether to show the planning calendar with or without multi-select mode, or whether users should be able to switch between the two modes. Hiding the interval appointments of every object is optional.

The planning calendar can also be used without a row header. In this case, the row header disappears and only the appointments are visible. It can be used to show the calendar of one object. Note that the control was built mainly to compare time slots of different objects. For this reason, the time axis is shown horizontally and, depending on the interval, the appointments might shrink to smaller size. In this case, the text is cut off rather than truncated.

Components

This section describes the various components of the planning calendar.

Parts of the planning calendar
Parts of the planning calendar

The control consists of different parts:

  1. Header
  2. Toolbar
  3. View switch
  4. Navigation
  5. Time strip for hours/days/months
  6. Row header
  7. Row
  8. List item
  9. Interval appointment
  10. Appointment

1. Header

The header contains the toolbar and the navigation.

2. Toolbar

The toolbar consists of the calendar title (optional) and the toolbar actions, including a default view switch. You can add generic and app-specific actions that are relevant for your use case (such as creating an appointment, search, settings, showing the calendar legend, and so on). Always place actions that affect the entire calendar in the toolbar.

For more information, check out the toolbar guideline article.

The generic actions are as follows:

Search
Create Appointment
Add New Contact (icon: add-contact)
Multi-Select Mode (icon: multi-select)
Legend (icon: legend)
Settings (icon: action-settings)
Full Screen (icon: full-screen/exit-full-screen)

3. View switch

The view switch allows the user to switch between different time intervals (calendar views). Depending on the number of available calendar views, the view switch can be a segmented button (four views or less) or a select control (five views or more).

The 1 Month view shows an entire month. On desktop devices, the 1 Month view always displays an interval of 31 days. When the displayed month is shorter (28, 29, 30 days), days from the following month are displayed. They have a different visual state and serve as navigation to the following month.

The 1 Month view has an additional style for half-column appointment distribution, which is mainly used to avoid overlapping. The property appointmentRoundWidth can be set to “HalfColumn” or “None” (default). Currently, the width of the appointment is always rounded to 12 hours.
Note: This property is also applied when the calendar interval type is Days and the view shows more than 20 days.

On size M and Size S, the 1 Month view is adaptive. It consists of a calendar and a list of appointments for the selected day.

If you offer the 1 Week view, we strongly recommend displaying a different number of days in the Days view (more or less than seven). Otherwise, the user might be confused, as navigation for the two views differs.

The default calendar views are Hours, Days, Months, 1 Week, and 1 Month. The app developer can choose which views to include, depending on the use case, and how many values are shown for each view. App developers can change the default number of values shown, but they should then ensure that the app is still responsive. The app developer can also create custom views.

Relative views

When you need to display a period that is not connected to a certain time/date, you can map the calendar to relative dates (in contrast to absolute dates, such as, “Week 1”, “Week 2”). For example, when you would like to divide the year into quarters.

The application developer specifies the names of the intervals in the time strip and the index picker, as well as the size of the interval. The index picker then configures how many days are in one interval. All this happens in the PlanningCalendarView, once the newly created relative property is set to “true”.

In addition, the application developer sets a minDate in the planning calendar, determining the start date of the relative views.

4. Navigation

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

5. Time strip for hours/days/months

The time strip reflects the selected view, and shows the hours, days or months that are currently visible. The first day of the week can be defined. If not defined, the default is taken from the current user locale.

In all views that show days (Days, 1 Week, 1 Month), you can display calendar weeks in an extra line below the time strip (property: showWeekNumbers).

6. Row header

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

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

7. Row

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

8. List item

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

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

9. Interval appointment

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

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

10. Appointment

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

There are four types of appointments:

  • Regular: Displayed in two rows. One-row display is also possible if the appointmentsReducedHeight property is set to “true”.
  • Half-size: Always displayed in one row, shows the title.
  • Large: Always displayed in three rows, also shows the description for each appointment (if available).
  • Automatic: The number of rows is determined automatically.
    Appointment Info Rows
    Title only 1 row
    Title + text
    or:
    Title + description
    2 rows
    Title + text + description 3 rows

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

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

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

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

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

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

Planning Calendar Legend

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

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

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

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

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

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

Guidelines
Ensure that colors are used consistently within your product area.

The Appointments section contains the color values for the available appointment types. The app developer has to define explicitly which color represents which type. The planning calendar legend does not take the color automatically from the planning calendar.

If combined appointments in the calendar are of the same type (in Months view), they take the color of that type. Combined appointments of different types are marked gray. We also recommend adding the gray color for mixed combined appointments to the Appointments section in the legend.

Planning calendar legend
Planning calendar legend
Developer Hint
To prevent waiting time, app developers should load the sap.ui.unified library.

Behavior and Interaction

To create an appointment, the user must trigger an action by clicking the Create button in the toolbar. You can also configure the control to create a new appointment when the user clicks directly on a row.

The user can click the appointment to see further details. The app development team must define what kind of information is then shown. For example, clicking an appointment can trigger a popover with detailed information.

Users can select more than one appointment at a time via Ctrl/Cmd + click. If the multipleAppointmentsSelection property is set to “true”, every appointment that the users click is selected.

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

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

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

View switch

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

Today

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

Back and forward navigation

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

Date picker

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

Snapping Header

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

Header snaps to top when scrolling down
Header snaps to top when scrolling down

Drag and Drop

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

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

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

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

Combined appointments and interval appointments are not draggable.

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop

Guidelines

Switching the Row Header

To enable end users to rearrange the planning calendar by switching the row header, you can implement a flexible row header. This is not done by the control and must be implemented by the app development team.

The list items in the row header can be a value of any attribute of an appointment. The appointment attributes are part of app-specific content, so they should be specified by the app development team. The control does not provide default attributes.

Our guideline is to use the select control in the place of the calendar title. The select control will contain all the attributes that can serve as the row header. When a different attribute is selected, the calendar is rearranged accordingly. You can also add a counter after the list items to indicate how many appointments fall into a specific group.

It is also possible to have both the calendar title and select control, in which case you should have first the title and then the select.

On small screen sizes, use select instead of the calendar title. If you want to keep the calendar title, place select in the overflow menu.

Resources

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

Elements and Controls

Implementation

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
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 L
Single planning calendar - Size M
Single planning calendar - Size M
Single planning calendar - Size S
Single planning calendar - Size S

Components

The single planning calendar consists of the following components:

  1. Header
  2. Toolbar
  3. View switch
  4. Navigation
  5. Date strip
  6. All-day appointment
  7. Timeline
  8. Appointment
  9. Calendar grid
  10. Now marker
Components of the single planning calendar
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
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 10 days - size L
Custom view 3 days - size S
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.

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
Appointment structure
Now marker - Current time replaces the full hour
Now marker - Current time replaces the full hour

Single Planning Calendar Legend

You can highlight special days within the calendar. A legend is used to define the meaning of the highlights. Users open the legend using the legend icon button in the toolbar (  ). Like all other actions in the toolbar, the app developer must add the legend button explicitly.

For details, see the legend sections for the Planning Calendar and Calendar.

Guidelines
Ensure that colors are used consistently within your product area.
Single planning calendar legend
Single planning calendar legend

Behavior and Interaction

Date Picker

The visible period is indicated with the date interval link in the navigation. Clicking the link opens a date picker, which helps the user to navigate quickly to a specific day or week.

Creating an Appointment

We recommend offering a Create action in the toolbar.

The UI for creating the appointment must be implemented at app level. The control provides only the underlying functionality for creating appointments. For most use cases, a dialog works best and is recommended (see sample dialog below).

First day of the week

You can set the day that displays as the first day of the week in the week and month views. Valid values are 0 to 6, starting with Sunday. If no value is set, the default of the used locale is used.

Zooming

To make appointments easier to read, you can implement the zoom behavior using the controls buttonstep input, or slider.

The scaleFactor property controls the zoom level. Its values can be numbers from 1 to 6. The number represents a multiplier for the height of the rows.

Viewing Appointment Details

The UI for viewing appointment details must be implemented at app level. The control provides only the underlying functionality for displaying appointment details. We recommend using a popover to keep the context for the user (see sample popover below).

Working Hours

You can opt to set working hours in the single planning calendar (properties: startHourendHour). 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).

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
Drag and drop into the all-day appointments area
Drag and drop into the all-day appointments area
Drag and drop from 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

Implementation

Select Dialog

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

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

Usage

Use the select dialog if:

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

Do not use the select dialog if:

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

Responsiveness

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

Size S

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

Size M

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

Size L

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

Components

Dialog Header

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

Single selection

Select

Example: Select Product

Multi-selection

Select

Example: Select Products

Search

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

Info Toolbar

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

Selected :

Example: Selected Products: 2

Content

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

Button Toolbar

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

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

Behavior and Interaction

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

Single Select

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

Multi-Select

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

Search

The user can search items.

Resize and Drag Dialog

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

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

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

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

Guidelines

List Options

If you need to indicate that none of the selection options are selected, or you need to allow users to not select an option, offer an appropriate option, such as (Not Selected) or (No Values Selected). Show this option in parentheses and place it at the beginning of the list.

Single selection list with '(Not Selected)' option
Single selection list with '(Not Selected)' option

Examples:

 (Not Selected)

 (Not Assigned)

 (No Product Selected)

 (None)

When using the select dialog for selecting filters: If you need to indicate that all items apply as filter options, provide All as an option and place it at the beginning of the list.

Filter list with 'All' option (no filters set)
Filter list with 'All' option (no filters set)

Search Behavior

Two types of search behavior are available:

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

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

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

Reset/Remember Selections

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

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

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

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

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

Infobar

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

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

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

Infobar States

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

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

“Clear” Button

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

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

Content

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

Resources

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

Elements and Controls

Implementation

Time Picker

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

When to Use

Use the time picker if:

  • Users need to select a time.
  • Users need to select a time range. In this case, one time picker can be used to set the starting time and a second one to set the end time.
  • Users need to select a specific duration, such as 1 minute and 30 seconds.

Do not use the time picker if:

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

Components

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

On phones, selecting the time input field opens a time input popover for entering the time with the touch keyboard.

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

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

Time Picker Popover

In the time picker popover, the user can select a time by using the clock face to set hours, minutes, and seconds. The full time is always displayed at the top of the popover.

The popover has the following parts:

  1. Hours field. Displays the hour entered or selected.
  2. Minutes field. Displays the minutes entered or selected.
  3. Seconds field (optional). Displays the seconds entered or selected. You can can removed the seconds field if it’s not relevant for your use case.
  4. AM/PM switch. The switch is displayed if the user has opted for the 12-hour format.
  5. Clock face for selecting the time. The appearance of the clock face depends on the focus (hours, minutes, or seconds) and the time format (12-hour or 24-hour clock).
  6. Footer with OK and Cancel buttons.
Components of the time picker popover
Components of the time picker popover

Hours Clock Face

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

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

Minutes Clock Face

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

Minutes clock face
Minutes clock face

Seconds Clock Face

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

Seconds clock face
Seconds clock face

Alternative triggers for the time picker popover

In addition to the time input field, you can set one of the following to trigger the time picker popover:

  • A button
  • A link
Button and link triggers for the time picker popover
Button and link triggers for the time picker popover

Behavior and Interaction

Users can enter the time in two ways:

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

Entering a Time in the Input Field

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

Entering a time directly
Entering a time directly

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

Time input popover on mobile/tablet devices

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

Time Selection with the Time Picker Popover

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

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

Minutes and seconds are selected in the same way.

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

Time selection on a desktop device
Time selection on a desktop device
Interaction options on mobile devices: Drag or tap
Interaction options on mobile devices: Drag or tap

Default Time

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

 

Preventing Errors

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

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

Now Button

You can offer a shortcut for setting the current time by displaying the Now icon button ( ) in the navigation part of the clock (sap.m.TimePicker, property: showCurrentTimeButton). Pressing the button changes the values to reflect the current time.

This property applies only to pickers that enable the selection of individual times. It has no effect on other pickers.

Selection of the current time with the 'Now' button
Selection of the current time with the 'Now' button

Style

The time picker has five basic value states:

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

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

Time picker value states
Time picker value states

Responsiveness

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

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

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

Guidelines

Time Formats

Seconds

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

Time Zone

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

For more information, see Formatting Time.

Properties

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

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

Related Links

Elements and Controls

Implementation

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 smartphone
Date picker on a desktop device
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 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.

It is possible to add additional descriptive texts to the input field (a unit of measurement, for example) by using a new association in the sap.m.InputBase control called ariaDescribedByThe association is responsible for referencing the elements that describe the control.

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
Date picker with a selected date and the current date
Clickable areas of the date picker
Clickable areas of the date picker
Date picker with highlighted days
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
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
Month view in the date picker
Year view in the date picker
Year view in the date picker
Year ranges 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
Date picker with footer

Behavior and Interaction

Selecting a Date

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

Date selection
Date selection

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

Navigating to the next month
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
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
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
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
Selecting another year

“Today” Button

You can offer a shortcut for navigating to the current date (sap.m.DatePicker, property: showCurrentDateButton). This displays an additional Today icon button ( ) in the navigation part of the calendar. Pressing this button sets the focus to the current date.

This feature is available for pickers that enable selection of individual days. For the others, the property has no effect.

Selecting the current date with the 'Today' button
Selecting the current date with the 'Today' button

Styles

Value States

The date picker supports the following value states:

  1. Regular
  2. Positive
  3. Warning
  4. Error
  5. 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
Date picker value states

Guidelines

Date Formats

Long Date Format

Use the long date format for a list in a list-detail layout / 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 a list in a list-detail layout / 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 a list in a list-detail layout / 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

Implementation

Dynamic Date Range

The dynamic date range is a standalone control that offers a choice of absolute and relative dates, using different offsets from the current date.

When to Use

Use the dynamic date range if:

  • You want to let users choose from a flexible set of absolute and relative dates and date ranges.
  • Your use case requires relative dates.

Do not use the dynamic date range if:

Components

The dynamic date range has two main components:

  1. Input with a button
  2. Dropdown list with options

Available Values

The control offers 29 default options for selecting dates, which cover different use cases.

Single Dates:

  • Date
  • Today
  • Yesterday
  • Tomorrow

Date Ranges:

  • Date range
  • From
  • To
  • Year to date
  • Date to year
  • Last x days / weeks / months / quarters / years
  • Next x days / weeks / months / quarters / years
  • Today -x / +y

Weeks:

  • This week
  • Last week
  • Next week

Months:

  • Month
  • This month
  • Last month
  • Next month

Quarters:

  • This quarter
  • Last quarter
  • Next quarter
  • First quarter
  • Second quarter
  • Third quarter
  • Fourth quarter

Years:

  • This year
  • Last year
  • Next year

Application development teams can also implement custom options and plug them into the control.

Guidelines
If you offer the option Last X Days and/or Next X Days, also include the options Yesterday and Tomorrow respectively.

This ensures that the display field automatically shows Yesterday or Tomorrow when the value for X is “1” (Last 1 Day, Next 1 Day).

Dynamic date range components
Dynamic date range components

Behavior and Interaction

If the user selects an option that requires specific user input, a subscreen opens for entering the values.

The existing date picker control is used for selecting dates.

Selecting a single date with the calendar
Selecting a single date with the calendar

The dynamic date control also comes with more complex options for selecting relative dates. For example, “Today -x / +y” days allows users to enter a timeframe that includes the current day by entering the number of days before “today” and the number of days after “today”.

'Today -x / +y' option to select a date range that includes the current day
'Today -x / +y' option to select a date range that includes the current day

Responsiveness

On desktop devices, clicking the input icon for the dynamic date range opens a dropdown list with the predefined options.

Dynamic date range in compact mode
Dynamic date range in compact mode

On mobile devices, tapping the input icon for the dynamic date range opens a full screen dialog. The dialog closes when the user selects a date or date range, or when the user taps Cancel.

Dynamic date range on mobile devices
Dynamic date range on mobile devices

Top Tips

  • Only offer options that are relevant for your use case.
  • You can also add your own values, if necessary.
  • If you use your own values, provide human readable text.

Related Links

Elements and Controls

Implementation

P13n Dialog

Warning
The sap.m.P13nDialog control has been deprecated. See the new control sap.m.p13n.Popup.

Intro

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

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

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

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

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

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

Usage

Use the P13n dialog if:

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

Do not use the P13n dialog if:

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

Responsiveness

The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), it shows as a centered dialog. For size S (smartphones), it displays as a full screen dialog.

Size S – Columns
Size S – Columns
Size M
Size M
Size L
Size L

Components

The P13n dialog consists of four different tabs that can be used separately or combined, as required by the use case:

  • Sort
  • Filter
  • Group
  • Columns

App developers can add more tabs manually.

Behavior and Interaction

Columns

The Columns tab allows users to change the visible table columns and the order in which they are displayed.

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

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

Show/Hide

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

Reorder

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

Search

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

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

Sort

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

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

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

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

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

Filter

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

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

Column

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

Operator

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

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

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

Available operators:

String (Text)

  • between
  • contains
  • equal to
  • begins with
  • ends with
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Number

  • between
  • equal to
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Date

  • between
  • equal to
  • after
  • on or after
  • before
  • before or on

Boolean (true/false)

  • equal to

Value

The last field contains the value by which the selected column is filtered. The kind of input field that is provided depends on the data type of the selected column and the selected operator. For example, the value field for fixed or Boolean values could be a dropdown list, an input field with suggestions, or a date picker. You can also offer two or even more fields if the use case requires it.

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

Group

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

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

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

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

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

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

Resources

Elements and Controls

Implementation

Filter Bar

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

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

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

When to Use

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

Do not use the filter bar:

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

Filter Bar Components

Expanded Filter Bar

The expanded filter bar consists of:

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

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

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

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

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

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

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

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

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

Collapsed Filter Bar

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

Collapsed filter bar
Collapsed filter bar

It shows a summary of the filters currently applied:

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

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

“Adapt Filters” Dialog

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

Adapt Filters dialog - list view, hidden values
Adapt Filters dialog - list view, hidden values

The Adapt Filters dialog consists of:

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

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

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

Searching and Displaying Filters in the Dialog

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

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

In the dialog, when a mandatory filter has:

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

In the dialog, users can display the filters:

  • With or without the filter values (2).

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

  • In the list or group view (3).

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

Displaying Filters in the Filter Bar

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

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

In the Adapt Filters footer bar (5):

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

Resetting Filters

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

Adapt Filters dialog - list view, values shown
Adapt Filters dialog - list view, values shown
Adapt Filters dialog - grouped view, hidden values
Adapt Filters dialog - grouped view, hidden values
Adapt Filters dialog - grouped view, values shown
Adapt Filters dialog - grouped view, values shown

Filter Input Controls

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

For Use
A predefined list for single or multiple selection The select control or combo box control
Temporal information The date picker or date range selector
Multi-input fields Suggestions to help the user enter a valid value

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

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

Developer Hint
For development information, see Data Types for the smart filter bar.

Behavior and Interaction

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

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

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

Responsiveness

The name of the view or title is always visible.

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

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

Examples

Top Tips

Filter Bar

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

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

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

Filter Input Controls

Preset Filter Values

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

Update Mode

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

Related Links

Elements and Controls

Implementation

Upload Set

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

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

When to Use

Use the upload set control if:

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

Do not use the upload set control if:

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

Components

  1. Toolbar with upload and download controls
  2. Edit and delete actions
  3. Technical status
  4. Attributes and statuses

Toolbar

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

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

List

Actions (2)

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

Technical statuses (3)

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

Attributes and statuses (4)

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

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

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

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

Behavior and Interaction

Uploading Files

The upload set offers two basic working modes:

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

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

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

Developer Hint

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

Empty State

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

Interaction - No items
Interaction - No items

Drag and Drop

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

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

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

Interaction - Drag and drop
Interaction - Drag and drop

Opening Files

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

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

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

Renaming Files

The Edit function works identically on desktop and mobile devices.

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

Deleting Files

The Delete function works identically on desktop and mobile devices.

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

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

Clickable Attributes

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

Examples:

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

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

Responsiveness

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

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

Example

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

Upload set in object page
Upload set in object page

Other possible scenarios:

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

Top Tips

When to Show, Disable, and Hide Actions

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

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

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

Related Links

Elements and Controls

Implementation

Upload Set

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

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

When to Use

Use the upload set control if:

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

Do not use the upload set control if:

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

Layout

Default Layout and Actions

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

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

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

Layout – Items
Layout – Items

Attributes and Statuses

You can display additional attributes and statuses below the file name. Attributes can include the name of the person who uploaded the file, the upload date, the version number, file size, and so on.

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

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

Layout – Attributes and statuses
Layout – Attributes and statuses

Technical Statuses

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

Layout – Technical statuses
Layout – Technical statuses

Behavior and Interaction

Uploading Files

The upload set offers two basic working modes:

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

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

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

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

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

Empty State

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

Interaction - No files found
Interaction - No files found

Drag and Drop

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

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

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

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

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

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

Opening Files

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

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

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

Renaming Files

The Edit function works identically on desktop and mobile devices.

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

Removing Files

The Remove function works identically on desktop and mobile devices.

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

Remove confirms the deletion and the file is removed from the list. Cancel aborts the process, closes the dialog, and brings the user back to the file list without making any changes.

Clickable Attributes

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

Examples:

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

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

Responsiveness

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

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

Example

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

Upload set in object page
Upload set in object page

Other possible scenarios:

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

Top Tips

When to Show, Disable, and Hide Actions

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

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

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

Custom Uploader

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

Related Links

Elements and Controls

Implementation

Dynamic Date Range

The dynamic date range is a standalone control that offers a choice of absolute and relative dates, using different offsets from the current date.

When to Use

Use the dynamic date range if:

  • You want to let users choose from a flexible set of absolute and relative dates and date ranges.
  • Your use case requires relative dates.

Do not use the dynamic date range if:

Components

The dynamic date range has two main components:

  1. Input with a button
  2. Dropdown list with options

Available Values

The control offers 29 default options for selecting dates, which cover different use cases.

Single Dates:

  • Date
  • Today
  • Yesterday
  • Tomorrow

Date Ranges:

  • Date range
  • From
  • To
  • Year to date
  • Date to year
  • Last x days / weeks / months / quarters / years
  • Next x days / weeks / months / quarters / years
  • Today -x / +y

Weeks:

  • This week
  • Last week
  • Next week

Months:

  • Month
  • This month
  • Last month
  • Next month

Quarters:

  • This quarter
  • Last quarter
  • Next quarter
  • First quarter
  • Second quarter
  • Third quarter
  • Fourth quarter

Years:

  • This year
  • Last year
  • Next year

Application development teams can also implement custom options and plug them into the control.

Guidelines
If you offer the option Last X Days and/or Next X Days, also include the options Yesterday and Tomorrow respectively.

This ensures that the display field automatically shows Yesterday or Tomorrow when the value for X is “1” (Last 1 Day, Next 1 Day).

Dynamic date range components
Dynamic date range components

Behavior and Interaction

If the user selects an option that requires specific user input, a subscreen opens for entering the values.

The existing date picker control is used for selecting dates.

Selecting a single date with the calendar
Selecting a single date with the calendar

The dynamic date control also comes with more complex options for selecting relative dates. For example, “Today -x / +y” days allows users to enter a timeframe that includes the current day by entering the number of days before “today” and the number of days after “today”.

'Today -x / +y' option to select a date range that includes the current day
'Today -x / +y' option to select a date range that includes the current day

Responsiveness

On desktop devices, clicking the input icon for the dynamic date range opens a dropdown list with the predefined options.

Dynamic date range in compact mode
Dynamic date range in compact mode

On mobile devices, tapping the input icon for the dynamic date range opens a full screen dialog. The dialog closes when the user selects a date or date range, or when the user taps Cancel.

Dynamic date range on mobile devices
Dynamic date range on mobile devices

Top Tips

  • Only offer options that are relevant for your use case.
  • You can also add your own values, if necessary.
  • If you use your own values, provide human readable text.

Related Links

Elements and Controls

Implementation

Dynamic Date Range

Information
The dynamic date range control is set to replace the existing dynamic date control, which is only supported for the smart filter bar. Currently, both controls are available in parallel.

Intro

The dynamic date range is a standalone control that offers a choice of absolute and relative dates, using different offsets from the current date.

When to Use

Use the dynamic date range if:

  • You want to let users choose from a flexible set of absolute and relative dates and date ranges.
  • Your use case requires relative dates.
  • You want to offer dynamic date range selection outside the smart filter bar (for example, in a table toolbar).

Do not use the dynamic date range if:

Components

The dynamic date range has two main components:

  1. Input with a button
  2. Dropdown list with options

Available Values

The control offers 29 default options for selecting dates, which cover different use cases.

Single Dates:

  • Date
  • Today
  • Yesterday
  • Tomorrow

Date Ranges:

  • Date range
  • From
  • To
  • Year to date
  • Date to year
  • Last x days / weeks / months / quarters / years
  • Next x days / weeks / months / quarters / years
  • Today -x / +y

Weeks:

  • This week
  • Last week
  • Next week

Months:

  • Month
  • This month
  • Last month
  • Next month

Quarters:

  • This quarter
  • Last quarter
  • Next quarter
  • First quarter
  • Second quarter
  • Third quarter
  • Fourth quarter

Years:

  • This year
  • Last year
  • Next year

Application development teams can also implement custom options and plug them into the control.

Dynamic date range components
Dynamic date range components

Behavior and Interaction

If the user selects an option that requires specific user input, a subscreen opens for entering the values.

The existing date picker control is used for selecting dates.

Selecting a single date with the calendar
Selecting a single date with the calendar

The dynamic date control also comes with more complex options for selecting relative dates. For example, “Today -x / +y” days allows users to enter a timeframe that includes the current day by entering the number of days before “today” and the number of days after “today”.

'Today -x / +y' option to select a date range that includes the current day
'Today -x / +y' option to select a date range that includes the current day

Responsiveness

On desktop devices, clicking the input icon for the dynamic date range opens a dropdown list with the predefined options.

Dynamic date range in compact mode
Dynamic date range in compact mode

On mobile devices, tapping the input icon for the dynamic date range opens a full screen dialog. The dialog closes when the user selects a date or date range, or when the user taps Cancel.

Dynamic date range on mobile devices
Dynamic date range on mobile devices

Top Tips

  • Only offer options that are relevant for your use case.
  • You can also add your own values, if necessary.
  • If you use your own values, provide human readable text.

Related Links

Elements and Controls

Implementation

Upload Set

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

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

When to Use

Use the upload set control if:

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

Do not use the upload set control if:

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

Layout

Default Layout and Actions

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

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

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

Layout – Items
Layout – Items

Attributes and Statuses

You can display additional attributes and statuses below the file name. Attributes can include the name of the person who uploaded the file, the upload date, the version number, file size, and so on.

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

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

Layout – Attributes and statuses
Layout – Attributes and statuses

Technical Statuses

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

Layout – Technical statuses
Layout – Technical statuses

Behavior and Interaction

Uploading Files

The upload set offers two basic working modes:

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

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

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

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

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

Empty State

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

Interaction - No files found
Interaction - No files found

Drag and Drop

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

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

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

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

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

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

Opening Files

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

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

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

Renaming Files

The Edit function works identically on desktop and mobile devices.

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

Removing Files

The Remove function works identically on desktop and mobile devices.

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

Remove confirms the deletion and the file is removed from the list. Cancel aborts the process, closes the dialog, and brings the user back to the file list without making any changes.

Clickable Attributes

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

Examples:

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

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

Responsiveness

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

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

Example

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

Upload set in object page
Upload set in object page

Other possible scenarios:

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

Top Tips

When to Show, Disable, and Hide Actions

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

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

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

Custom Uploader

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

Related Links

Elements and Controls

Implementation

Upload Set

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

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

When to Use

Use the upload set control if:

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

Do not use the upload set control if:

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

Layout

Default Layout and Actions

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

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

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

Layout – Items
Layout – Items

Attributes and Statuses

You can display additional attributes and statuses below the file name. Attributes can include the name of the person who uploaded the file, the upload date, the version number, file size, and so on.

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

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

Layout – Attributes and statuses
Layout – Attributes and statuses

Technical Statuses

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

Layout – Technical statuses
Layout – Technical statuses

Behavior and Interaction

Uploading Files

The upload set offers two basic working modes:

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

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

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

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

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

Empty State

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

Interaction - No files found
Interaction - No files found

Drag and Drop

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

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

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

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

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

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

Opening Files

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

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

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

Renaming Files

The Edit function works identically on desktop and mobile devices.

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

Removing Files

The Remove function works identically on desktop and mobile devices.

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

Remove confirms the deletion and the file is removed from the list. Cancel aborts the process, closes the dialog, and brings the user back to the file list without making any changes.

Clickable Attributes

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

Examples:

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

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

Responsiveness

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

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

Example

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

Upload set in object page
Upload set in object page

Other possible scenarios:

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

Top Tips

When to Show, Disable, and Hide Actions

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

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

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

Custom Uploader

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

Related Links

Elements and Controls

Implementation

Time Picker

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

When to Use

Use the time picker if:

  • Users need to select a time.
  • Users need to select a time range. In this case, one time picker can be used to set the starting time and a second one to set the end time.
  • Users need to select a specific duration, such as 1 minute and 30 seconds.

Do not use the time picker if:

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

Components

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

On phones, selecting the time input field opens a time input popover for entering the time with the touch keyboard.

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

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

Time Picker Popover

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

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

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

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

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

Hours Clock Face

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

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

Minutes Clock Face

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

Minutes clock face
Minutes clock face

Seconds Clock Face

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

Seconds clock face
Seconds clock face

Behavior and Interaction

Users can enter the time in two ways:

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

Entering a Time in the Input Field

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

Entering a time directly
Entering a time directly

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

Time input popover on mobile/tablet devices

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

Selecting a Time with the Time Picker Popover

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

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

Minutes and seconds are selected in the same way.

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

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

Default Time

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

 

Preventing Errors

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

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

Style

The time picker has five basic value states:

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

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

Time picker value states
Time picker value states

Responsiveness

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

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

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

Guidelines

Time Formats

Seconds

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

Time Zone

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

For more information, see Formatting Time.

Properties

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

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

Related Links

Elements and Controls

Implementation

Dynamic Date (Smart Filter Bar)

The dynamic date is a smart control that is only available in the smart filter bar. When the user enters a value in the date field, it suggests corresponding fixed and dynamic dates. It also offers a value help feature that lets users choose between different time periods and define them further.

The set of values offered must be defined by the app.

Usage

Use the dynamic date control if:

  • You need flexibility between fixed and dynamic dates.
  • You need dynamic dates that can be saved in the variant management (for example, show values from today regardless of when you open the app).
  • You are using the smart filter bar.
  • The user only needs to select one value.

Do not use the dynamic date control if:

Responsiveness

The dynamic date control is fully responsive. It provides a touch-friendly screen in sizes S and M (cozy mode) and is smaller in size L (compact mode). For more information on cozy and compact modes, see the article on content density.

Value help for dynamic date range – Size S
Value help for dynamic date range – Size S
Value help for dynamic date range – Size L
Value help for dynamic date range – Size L

Components

The two clickable areas of the dynamic date control
The two clickable areas of the dynamic date control

The dynamic date consists of two components:
(A) Date input field with suggestions
(B) Value help popover

On all devices, users can either use the input field to type a date, or use the value help button to open the popover.

Dynamic Date Input Field

The user can type data directly into the input field. Upon user input, a list of suggestions appears.

Value Help Popover

The value help popover offers all available values the user can choose from. Depending on the selected time period, the popover shows different controls. It either shows:
(A) An input field
(B) One or two date pickers
(C) A read-only text with the chosen date range
(D) A select control

Value help popover – Input field
Value help popover – Input field
Value help popover – Date pickers
Value help popover – Date pickers
Value help popover – Read only
Value help popover – Read only
Value help popover – Select control
Value help popover – Select control

Values Offered

  • From
  • To
  • Date Range
  • Today
  • Today -X / +Y days
  • Last X days
  • Next X days
  • This week
  • Last week
  • Last X weeks

Offered Values

  • Next week
  • Next X weeks
  • Month
  • This month
  • Last month
  • Last X months
  • Next X months
  • This quarter
  • Last quarter
  • Last X quarters
  • Next quarter

Offered Values

  • Next X quarters
  • First quarter
  • Second quarter
  • Third quarter
  • Fourth quarter
  • This year
  • Last year
  • Last X years
  • Next year
  • Next X years
  • Year to date

Behavior & Interaction

Typing data into the date range input field

The user can type keywords or numbers into the date range input field.  For example, if the user types a number, the system automatically suggests possible dates. All dynamic dates show the actual dates to help the user select the right value.

List of suggestions shown after typed input
List of suggestions shown after typed input

Opening the value help and selecting a time period

Clicking the value help icon opens a popover with additional options for defining the time period. The user can choose from several time periods by clicking the down arrow in the select control. Once a time period has been chosen, the selection box closes.

Opening the value help popover and selecting a time period
Opening the value help popover and selecting a time period

Defining a custom time period (X)

If the user selects a custom time period with “X”, such as Last X days, the control shows a simple input field for entering the number. The text in the date input field changes according to the user’s input.

Custom time period with a simple input field
Custom time period with a simple input field

Selecting a date range

If the user selects a time period that requires input of a start and end date, two date pickers appear. These can be opened by clicking the calendar icon. The text in the date range input field changes according to the user’s input.

Selected time period with two date pickers (start date and end date)
Selected time period with two date pickers (start date and end date)

Styles

Validation

Use inline validation to give the user feedback, especially for errors and warnings. The possible states are “warning”, “error”, and “success”.

The dynamic date input field in question is highlighted by a frame in the corresponding color. If the focus is inside the field, an explanation is shown. Ensure that this explanation is as specific as possible.

Visible frame that shows an error when the field is out of focus
Visible frame that shows an error when the field is out of focus
Error state with meaningful text – The date range input field is in focus
Error state with meaningful text – The date range input field is in focus

Guidelines

See the Date Picker and Date Range Selection articles for the guidelines. They also apply to the dynamic date control.

 

List of Options

  • Only provide values that are relevant for the use case in the list of options.
  • You can also add your own values, if necessary.
  • If you use your own values, provide human readable text.

Resources

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

Elements and Controls

Implementation

Step Input

The step input control allows the user to change the input values in predefined increments (steps).

Usage

Use the step input if:

  • The user needs to adjust amounts, quantities, or other values quickly.
  • The user needs to adjust values for a specific step (for example, in a shopping cart).

Do not use the step input if:

  • The user needs to enter a static number (for example, postal code, phone number, or ID). In this case, use the regular input field control instead.
  • You want to display a value that rarely needs to be adjusted and does not pertain to a particular step. In this case, use the regular input field control instead.
  • You want the user to enter dates and times. In this case, use the date pickerdate range selectiontime picker, or date/time picker instead.

Responsiveness

Size S and M (Smartphone and Tablet)

On smartphones and tablets, the step input is shown in cozy mode. When the focus is in the input field, the keyboard layout for numeric input is displayed.

Size L (Desktop)

On desktop devices, the step input is shown in compact mode.

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

Step input - size S/M
Step input - size S/M
Step input - size L
Step input - size L

Components

The step input consists of:

(A) Input field
(B) Button to decrease the value
(C) Button to increase the value

Step input areas
Step input areas

You can show a descriptive reference or unit of measurement after the field (property: description). Depending on your use case, you may need to adjust how the space is distributed between the input field and the descriptive text (property: fieldWidth).

Step input with description
Step input with description

Behavior and Interaction

Default Value

The step input always contains a value. When no value is set, the default value is generally 0. However, app developers can set a different default value (property: value).

If the minimum value is larger than 0, the generic value is the minimum value set by the app team.

Changing the Value

The user changes the value:

  • By pressing the increase/decrease buttons
  • By typing a number
  • With keyboard shortcuts (up/down, page up/down)
  • With the mouse scroll wheel

On desktop devices, clicking the input field places the cursor in the input field. On mobile devices, tapping the input field displays the numeric keyboard.

Clicking the buttons changes the value by a step and does not place the caret in the input field.

When the user clears the value and leaves the input field, the value in the field becomes 0 or the minimum if the minimum is larger than 0.

If the user enters an invalid value, the invalid value remains in the input field. An error state is displayed.

Increasing the Step

To allow the user to change values by a larger step with keyboard shortcuts, app developers can set a multiple of the step (property: largerStep). The default value is two times the set step.

If your use case requires more complex step increments (for example, if you want the step increment to be the closest number that is divisible by the defined step) you can use the stepMode property. For details, please refer to the API reference.

Maximum and Minimum Values

App developers can set a maximum and minimum value for the step input.

When the maximum/minimum values are reached, the Increase/Decrease button and up/down keyboard navigation are disabled.

Display Value

The step input control allows decimal values and can control the number of digits shown after the decimal point (property: displayValuePrecision). When the property is set to a specific value – from 0 (default) to 20 – the control restricts users accordingly as they type or paste a value. Trying to type more digits triggers an error state.

Step input at maximum value (max = 100)
Step input at maximum value (max = 100)
Step input at minimum value (min = -100)
Step input at minimum value (min = -100)

Styles

Editable and Enabled States

Editable

Property settings: editable = true, enabled = true

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

Read-only state
Read-only state
Disabled state
Disabled state

Value States

The step input control offers the four value states listed below. For the error, warning, and information states, you can show an additional value state text when the focus is on the input field. If the text gets too long, it wraps.

  • Warning
  • Error
  • Success: No value state message is shown
  • Information: Value state message can show additional information, such as recommendations.

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

For more information on showing value states in a form, see Form Field Validation.

Error state
Error state
Warning state
Warning state
Success state
Success state
Information state
Information state
Error state – With value state text
Error state – With value state text
Warning state – With value state text
Warning state – With value state text
Success state – No value state text
Success state – No value state text
Information state – With value state text
Information state – With value state text

Guidelines

Always provide a meaningful label for the step input.

Width

By default the width of the step input is set to 100% of the container. Avoid setting a fixed width, but rather embed the control in a proper layout such as a form, simple form, or grid layout, and use the layout data property where the width is defined by the 12-column approach to define the responsive behavior for sizes S, M, and L.

When used in forms, the width of the step input control comes from the label:field ratio of the form. The app development team should be able to restrict the width to a proper number of columns (12-grid responsive layout) so that the step input is not too wide.

Ensure an appropriate width for the range of values to be entered for all the sizes S, M, and L. Avoid a larger width than necessary.

Keep in mind the varying lengths of decimals. Limit the number of digits after the floating point if possible in your use case. For more information, have a look at the article on formatting numbers.

Resources

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

Elements and Controls

Implementation

Multi-Input Field

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

Usage

Use the multi-input field if:

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

Do not use the multi-input field if:

  • You want the user to select one entry only. In this case, use the input field or combo box instead.
  • You want the user to select from a pre-defined set of options only. In this case, use the multi-combo box instead.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

Size S

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

Size M

  • Cozy mode.
  • The suggestions appear below or above the multi-input field.
  • The user can review tokens by swiping them to the left or right.
Suggestions on a tablet (size M)
Suggestions on a tablet (size M)

Size L

  • Compact mode.
  • The suggestions appear below or above the multi-input field.
  • The user can review tokens by pressing the right or left arrows on the keyboard.
Suggestions on a desktop device (size L)
Suggestions on a desktop device (size L)

Types

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

Behavior and Interaction

Adding Tokens

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

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

The suggestions dropdown can be wider than the input field itself, but not wider than the current browser window (property: maxSuggestionWidth).

Warning
The typeahead input feature is not available for Android devices.
Developer Hint
Values that are entered can also be tokenized when the user presses ENTER. The app development team can perform a custom validation of the entered data and decide whether a token should be created.
A token in a multi-input field
A token in a multi-input field
A multi-input field with two tokens while editing
A multi-input field with two tokens while editing
Information
For information on how to manage leading and treading whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Reviewing Tokens

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

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

Multi-input field - 'n More' label (desktop)
Multi-input field - 'n More' label (desktop)
More items displayed (desktop)
More items displayed (desktop)
More items displayed (phone)
More items displayed (phone)

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

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

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

Multi-input field - '1 Item' case (desktop)
Multi-input field - '1 Item' case (desktop)
Showing the compete item
Showing the compete item
Multi-input field - 'n Items' label (desktop)
Multi-input field - 'n Items' label (desktop)
Displaying all items
Displaying all items

In the input field itself, the user can review tokens using the left or right cursor keys on a desktop, or by swiping to the left or right on a smartphone or tablet. Tokens can be selected by either clicking/tapping them or by pressing Space (selects the focused token).

Selected token
Selected token

Deleting Tokens

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

Using Value Help

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

Value help icon on empty multi-input field
Value help icon on empty multi-input field
Select Dialog
Select Dialog
Selecting Items
Selecting Items
Displaying the selected items in the multi-input field
Displaying the selected items in the multi-input field
Value help icon on empty multi-input field
Value help icon on empty multi-input field
Value help dialog
Value help dialog
Selecting Items
Selecting Items
Displaying the selected items in the multi-input field
Displaying the selected items in the multi-input field

To give a better indication of the type of data that can be selected, you can exchange the value help icon.

Custom value help icon
Custom value help icon

Filtering

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

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

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

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

Copying and Pasting Data from a Spreadsheet or Text File

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

Grouping

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

The group headers are not interactive.

The column headers within the tabular suggestion list remain in place when the list is scrolled (“sticky” behavior). Make sure the suggestion list has no more than 4 columns. If the columns don’t all fit on the screen or get too narrow on small screens, enable the responsive behavior to move columns into the pop-in area (property: enableTableAutoPopinMode).

Multi-input with grouped suggestions
Multi-input with grouped suggestions
Multi-input with grouped tabular suggestions
Multi-input with grouped tabular suggestions
Multi-input field with grouped tabular suggestions making use of the table's pop-in behavior
Multi-input field with grouped tabular suggestions making use of the table's pop-in behavior

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

Clear

You can add a  (Clear) icon to the input field (property: showClearIcon). The icon appears as soon as the multi-input field has non-tokenized text. Clicking the Clear icon removes the non-tokenized text from the field.

If you offer the Clear icon, make sure that the multi-input field is wide enough to show the icon in addition to the value.

Multi input field with token
Multi input field with token
Multi input field with token, text, and 'Clear' icon
Multi input field with token, text, and 'Clear' icon

Styles

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

Unselected
Unselected
Unselected with predefined placeholder
Unselected with predefined placeholder
Unselected on hover
Unselected on hover
In focus
In focus
Selected items shown as tokens
Selected items shown as tokens
Expanded multi-selection
Expanded multi-selection

When an error, warning, or information value state is displayed, the details can be provided as text or formatted text. The text is shown when the corresponding control has the focus. If using a formatted text, you can include one or several links.

Error
Error
Warning
Warning
Success
Success
Information
Information

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

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

Guidelines

  • Give the control a width that is appropriate for the range of values that are going to be entered. Try to avoid setting a fixed width on this control. Instead, embed it in a proper layout (such as a form, simple form, or grid layout) and work with the layout data property.
  • Provide meaningful labels for all input fields. Do not use the placeholder as a replacement for the label. The placeholder should only provide an additional hint.
  • The multi-input field can currently contain tokens and one free text value. If you allow only validated values, display an error or warning when the user tries to leave the field to indicate that the value entered is invalid, or remove the value.
  • If users try to select an item that has been selected before, we recommend setting an error state and providing a meaningful message.
Multi-input - Error state for an item that has already been selected
Multi-input - Error state for an item that has already been selected
  • You can use the layout options of the form to add the unit of measurement (UoM) after the multi-input control. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.
Developer Hint

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

  • The multi-input field can be used in the grid tableanalytical table and tree table as well, as condensed mode is already supported, both for desktop and mobile (tablets).
Multi-input field in the grid table in condensed mode
Multi-input field in the grid table in condensed mode
  • In display mode, use a text. Show the texts of the tokens, separated by bullet points. Provide an overflow for all texts that do not fit in one line.
  • In display mode, consider the following alternatives:
    • A bulleted list with a bullet per token text (for example, using formatted text)
    • A horizontal list with bullet separators between the individual token texts (for example, using text or formatted text)
    • If the display mode equivalent needs to be a single-line text (as required for the grid table, tree table, analytical table), provide an overflow for all texts that do not fit onto the line (for example, by adding a link, opening a popover, or using an expandable text).
Recommend display-mode equivalent
Recommend display-mode equivalent
Recommended display-mode equivalent with overflow indicator
Recommended display-mode equivalent with overflow indicator
Recommended display mode equivalent with overflow opened
Recommended display mode equivalent with overflow opened

Properties

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

Resources

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

Elements and Controls

Implementation

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:

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
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 feature on a tablet
Tabular autocomplete suggestion with sticky header
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
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
Input type text – Keyboard layout on a smartphone

Number

Input type number – Keyboard layout on a smartphone
Input type number – Keyboard layout on a smartphone

Email

Input type email – Keyboard layout on a smartphone
Input type email – Keyboard layout on a smartphone

URL

Input type URL – Keyboard layout on a smartphone
Input type URL – Keyboard layout on a smartphone

Telephone Number

Input type telephone number – Keyboard layout on a smartphone
Input type telephone number – Keyboard layout on a smartphone

Password

Input type password – Keyboard layout on a smartphone
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
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:

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

  1. Error
  2. Warning
  3. Success (no message is available for this state)
  4. Information

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

Input field in semantic colors with value state message below
Input field in semantic colors with value state message below

The value state message can be either a plain text or a formatted text.

Enabled, Read-only and Disabled states

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

  1. Enabled: This is the default setting.
  2. Read-only: The input field isn’t shown, just the value. This is used in display-only forms.
  3. 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 - Enabled
Input field - Read only
Input field - Read only
Input field - Disabled
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
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
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
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. To give a better indication of the type of data that can be selected, you can exchange the value help icon (property: valueHelpIconSrc). Once the value help option is enabled, the click event can be registered and one of the following displayed:

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
Input field with value help
Value help only
Value help only
Custom value help icon
Custom value help icon

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. By default, the width of the suggestion box is the same as the width of the input field. You can change it with the maxSuggestionWidth property.
Note: The maximum width of the suggestion box is always slightly smaller than the width of the screen or browser window (with 1 rem of free space on the left and right sides), regardless of the value you provide for maxSuggestionWidth.

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. 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. 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 suggestionItemssap.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
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 suggestionItemssap.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
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. If there are too many columns for the available space, the width of the columns shrinks. Alternatively, you can enable the responsive behavior of the table (property: enableTableAutoPopinMode).

To use the tabular suggestion feature, use the suggestionColumns aggregation to define the columns and the correct responsive behavior for the pop-in content. 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:

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, suggestion box wider than the input field
Tabular autocomplete, suggestion box wider than the input field

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 suggestions
Input with grouped tabular suggestions
Input with grouped tabular suggestions

Clear

You can add a Clear icon to the input field (property: showClearIcon). It will appear as soon as the input field has a value. Clicking the Clear icon removes the value from the field. If used, make sure that the input field is wide enough to show the Clear icon in addition to the value.

'Clear' icon
'Clear' icon

Accessibility

  • The property ariaDescribedBy links the input field to other controls to provide additional information for assistive technologies, such as screen readers. If you use this property, we recommend linking either to on-screen controls that provide additional context or to an invisible text.

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

Alignment

The alignment rules are the same for display mode and edit mode.

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 fieldcombo boxmulti-combo box, and select controls.

Input field – 'New' action
Input field – 'New' action
Input field – 'Edit' 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

Implementation

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
Filter bar with multi-combo box - Size S
Option list in full screen - Size S
Option list in full screen - Size S

Size M

Filter bar with multi-combo box - Size M
Filter bar with multi-combo box - Size M

Size L

Filter bar with multi-combo box - 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
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
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 (space bar or Enter).

The user clicks the input field to place the cursor in the field (1). Clicking the down arrow displays the list (2). As the user types into the input field, the list is filtered accordingly (3). The arrow up and arrow down keys 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 space bar on the keyboard, the text entered in the 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.

The shift key can be used to select a range of items (shift+click marks the end of the range, shift+arrow up / shift+arrow down extends or narrows the selection range in the corresponding direction. Ctrl+A selects or deselects all items. If selecting all items is a common use case, you can also show a Select All checkbox at the top of the list (property: showSelectAll).

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
Behavior - Sizes M and L
'Select All' check box (optional)
'Select All' check box (optional)

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
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 - '1 Item' case (desktop)
Multi-combo box - 'n Items' label (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
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.

Grouping
Grouping
Grouping on phones
Grouping on phones

Clear

You can add a  (Clear) icon to the combo box (property: showClearIcon). The icon appears as soon as the combo box has non-tokenized text. Clicking the Clear icon removes the non-tokenized text from the field.

If you offer the Clear icon, make sure that the multi-combo box is wide enough to show the icon in addition to the value.

'Clear' icon
'Clear' icon

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
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
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
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
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
Unselected with predefined placeholder
Unselected with predefined placeholder
Unselected on hover
Unselected on hover
On focus
On focus
Expanded
Expanded
Hover highlighting in list
Hover highlighting in list
Expanded selection
Expanded selection
Expanded multi-selection
Expanded multi-selection
Selected items shown as tokens
Selected items shown as tokens

The multi-combo box offers four value states:

  • Error
  • Warning
  • Success
  • Information

For error, warning, and information states, you can show an additional value state text message when the focus is on the combo box. The message can either be a plain text or a formatted text.

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

Error
Error
Warning
Warning
Success
Success
Information
Information

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

Don’t disable items in the option list. If an item can’t be selected, hide it.

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
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
Alphabetical multi-combo box
  • Numeric: Sort numeric values into a sequential order with the lowest number first.
Numeric multi-combo box
Numeric multi-combo box
  • Chronological: Sort time-related information into chronological order with the most recent first (if applicable).
Chronological multi-combo box
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. To avoid this, you can enable wrapping (property: wrapping).

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.

Alternatives for Display Mode

If a form or table supports both display and edit mode, use the multi-combo box only in edit mode. In display mode, consider the following alternatives:

  • A horizontal list with bullet separators between the individual token texts (for example, using text or formatted text).
  • A bulleted list with a bullet per token text (for example, using formatted text).

If the display mode equivalent needs to be a single-line text (as required for the grid table, tree table, analytical table), provide an overflow for all texts that do not fit onto the line (for example, by adding a link, opening a popover, or using an expandable text).

Recommend display mode equivalent
Recommend display mode equivalent
Recommended display mode equivalent with overflow indicator
Recommended display mode equivalent with overflow indicator
Recommended display mode equivalent with overflow opened
Recommended display mode equivalent with overflow opened

Resources

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

Elements and Controls

Implementation

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 S
Size S

Size M

Size M
Size M

Size L

Size L
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 S
Size M/L
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
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
Grouped suggestion list - Size S
Grouped suggestion list - Size S

Clear

You can add a  (Clear) icon to the combo box (property: showClearIcon). The icon appears as soon as the combo box has a value. Clicking the Clear icon removes the value from the field.

If you offer the Clear icon, make sure that the combo box is wide enough to show the icon in addition to the value.

'Clear' icon
'Clear' icon

Behavior and Interaction

Select a Value

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

  1. Select the item directly from the dropdown list.
  2. Type the item into the input field.
  3. 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
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 and autocomplete
Combo box - Default filtering in both columns 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 – Minimum width
Option list adapts to long entries
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
Unselected with predefined placeholder
Unselected with predefined placeholder
Unselected on hover
Unselected on hover
Arrow on hover
Arrow on hover
Focus
Focus
Expanded
Expanded
Autocomplete
Autocomplete

The combo box offers four value states:

  • Error
  • Warning
  • Success
  • Information

For error, warning, and information states, you can show an additional value state text message when the focus is on the combo box. The message can either be a plain text or a formatted text.

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

Error
Error
Warning
Warning
Success
Success
Information
Information
Warning message with long, wrapping text
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.

Don’t disable items in the option list. If an item can’t be selected, hide it.

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

Implementation

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 - Compact mode
Date/time picker - Cozy 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 the date/time icon in the input field. 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 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.

If there is no value in the input field, no date is selected in the calendar. The user needs to explicitly select a date. If a date is already selected and the user changes the year or the month, they need to explicitly select the date again to confirm the change.

Date/time picker – Entering data with input and picker
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
Date/time picker - Smartphone view

“Today” Button

You can offer a shortcut for navigating to the current date (sap.m.DateTimePicker, property: showCurrentDateButton). This displays an additional Today icon button ( ) in the navigation part of the calendar. Pressing this button sets the focus to the current date.

This feature is available for pickers that enable selection of individual days. For the others, the property has no effect.

'Today' button for selecting the current date
'Today' button for selecting the current date

Styles

Value States

The Date/Time picker supports the following value states:

  1. Regular
  2. Success
  3. Warning
  4. Error
  5. 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
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.

Date Input Field

It is possible to add additional “description” texts to the input field (a unit of measurement, for example) by using a new association in the sap.m.InputBase control called ariaDescribedByThe association is responsible for referencing the elements that describe the control.

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

Implementation

Date Range Selection

The control for selecting the date range is a single-field input control. Users can enter a localized date range using touch, mouse, or keyboard input, or by selecting a date range in the calendar. They can also navigate directly from one month or year to another.

Usage

Use the date range selection if:

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

Do not use the date range selection if:

  • You want to enter a date and a time. In this case, use the date picker or time picker instead.
  • The user’s primary goal is not to select ranges. If this is the case, use the simple date picker.
  • You want to let users choose from a flexible set of absolute and relative dates and date ranges. In this case, use the dynamic date range.

Responsiveness

The date range selection is fully responsive. It is smaller in compact mode and provides a touch-friendly size in cozy mode. For more information about cozy and compact modes, see the article on content density.

Date range selection (size S)
Date range selection (size S)
Date range selection (size L)
Date range selection (size L)

Components

The date range selection consists of two components: the date range input field (1) and the date range picker (2).

The two clickable areas of the date range selection on all devices
The two clickable areas of the date range selection on all devices

Date Range Input Field

The user can type the date directly into the input field, or use the date picker. You can also show a prompt text in the field (property: placeholder). The system validates the date and gives the user feedback.

1. Current day

2. Currently selected date range

It is possible to add additional descriptive texts to the input field (a unit of measurement, for example) by using a new association in the sap.m.InputBase control called ariaDescribedByThe association is responsible for referencing the elements that describe the control.

The dates December 19–22 are selected, and December 5 is shown as the current day
The dates December 19–22 are selected, and December 5 is shown as the current day

Date Range Picker

With the date range picker, the user can see a day view, month view, or year view. The current day and the selected date are highlighted. The calendar week is also visible in the day view. The calendar closes when a final day is selected. The user can click the arrows to view the previous and next days, months, or years (depending on the current view).

The selected date is shown with a blue background. The current day is indicated with a purple border in the calendar.

1. Previous month

2. Quick month selection

3. Quick year selection

4. Next month

5. Day selection

Clickable areas of the date range selection
Clickable areas of the date range selection

Optionally, you can offer a footer with OK and Cancel buttons. This gives users an alternative way of confirming the selected date range.

Date range picker with 'OK' and 'Cancel'
Date range picker with 'OK' and 'Cancel'

Behavior and Interaction

Selecting a Date Range

The user can type two dates into the date range input field or click the calendar icon to open the calendar and select a date. These two possibilities work for all devices – desktops, tablets, and smartphones.

Switch View

Clicking an arrow shows the next or previous day, month, or year.

Navigating to the next month
Navigating to the next month

Clicking the month shows an overview of all months.

Opening the month picker
Opening the month picker

If the current month is clicked, the user can change the month. When the user selects a month, the view changes to the day view.

Changing the month navigates back to the date picker. The focus is on the last selected start date.
Changing the month navigates back to the date picker. The focus is on the last selected start date.

By clicking the current year, the view changes to the year view. When the user selects a year, the view changes to the day view.

Opening the year picker
Opening the year picker

Selecting a Range

After the user selects a start date, the dates being hovered over turn light blue to provide visual feedback that a range is being selected. When the user selects an end date, the calendar closes. The range appears in the date input field.

Selecting the start date
Selecting the start date
Selecting the end date
Selecting the end date

Entering Single Dates

The date range selection also allows the user to input single dates. The user can type one date into the input field, or select the same day as a start and end date in the calendar.

“Today” Button

You can offer a shortcut for navigating to the current date (sap.m.DateRangeSelection, property: showCurrentDateButton). This displays an additional Today icon button ( ) in the navigation part of the calendar.

When the user clicks the Today button, the system automatically makes the current date the starting date for the new date range.

If the user has already selected the first date in the date range and then clicks the Today button, the focus is set to the current date. The system cancels the previous selection and makes the current day the starting date for the new selection.

This feature is available for pickers that enable selection of individual days. For the others, the property has no effect.

Selecting current date with the 'Today' button
Selecting current date with the 'Today' button

Styles

Delimiter

The delimiter visualizes the start and end date. If no delimiter is given, the app uses the one defined for the used locale.

Placeholder

If no range is selected, show a placeholder text to indicate the correct format. If no placeholder is defined, the control shows the default locale placeholder format. You can define your own placeholder, but you must also take localized versions into account.

Date range selection with default placeholder
Date range selection with default placeholder

Validation

Use inline validation to give the user feedback, especially for errors and warnings. Possible validation states are warning, error, success, and information. The date range input field in question is highlighted by a frame in the corresponding color. If the focus is inside the field, an explanation is shown. Ensure that this explanation is as specific as possible.

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

Visible frame that shows an error when the field is out of focus
Visible frame that shows an error when the field is out of focus
Error state with meaningful text; the date range input field is focused
Error state with meaningful text; the date range input field is focused
Visible frame that shows a warning when the field is out of focus
Visible frame that shows a warning when the field is out of focus
Warning state with meaningful text; the date range input field is focused
Warning state with meaningful text; the date range input field is focused
Visible frame that shows that additional information is available
Visible frame that shows that additional information is available
Information state with additional information, such as a recommendation
Information state with additional information, such as a recommendation

Guidelines

Display Format

You can choose whether the displayed texts are to be shown in short, medium, or long format, or in another date format like dd–MM–yyyy. However, other date formats (besides short, medium, and long) should be used carefully due to local dependencies.

Long display format
Long display format
Medium display format
Medium display format
Short display format
Short display format

Input Types

The following input types are available. (Note: these examples show German date formats for January 14, 2014.)

  • Unicode CLDR short format: 14.01.14
  • Unicode CLDR medium format: 14.01.2014
  • ISO date format: 2014-01-14
  • ISO date format without delimiters: 20140114
  • Unicode CLDR short format without delimiters: 140114
  • Unicode CLDR medium format: 14012014

Date Formats

Long Date Format

Use the long date format for a list in a list-detail layout / 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 a list in a list-detail layout / 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 a list in a list-detail layout / 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.

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

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

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

Resources

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

Elements and Controls

Implementation

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 smartphone
Date picker on a desktop device
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 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.

It is possible to add additional descriptive texts to the input field (a unit of measurement, for example) by using a new association in the sap.m.InputBase control called ariaDescribedByThe association is responsible for referencing the elements that describe the control.

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
Date picker with a selected date and the current date
Clickable areas of the date picker
Clickable areas of the date picker
Date picker with highlighted days
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
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
Month view in the date picker
Year view in the date picker
Year view in the date picker
Year ranges 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
Date picker with footer

Behavior and Interaction

Selecting a Date

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

Date selection
Date selection

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

Navigating to the next month
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
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
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
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
Selecting another year

“Today” Button

You can offer a shortcut for navigating to the current date (sap.m.DatePicker, property: showCurrentDateButton). This displays an additional Today icon button ( ) in the navigation part of the calendar. Pressing this button sets the focus to the current date.

This feature is available for pickers that enable selection of individual days. For the others, the property has no effect.

Selecting the current date with the 'Today' button
Selecting the current date with the 'Today' button

Styles

Value States

The date picker supports the following value states:

  1. Regular
  2. Positive
  3. Warning
  4. Error
  5. 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
Date picker value states

Guidelines

Date Formats

Long Date Format

Use the long date format for a list in a list-detail layout / 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 a list in a list-detail layout / 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 a list in a list-detail layout / 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

Implementation

Mask Input

The mask input control (sap.m.MaskInput) governs what a user is permitted to enter in an input field. It allows users to easily enter data in a certain format and in a fixed-width input (such as a date, time, phone number, credit card number, currency, and IP address).

Usage

Use mask input if:

  • You have to govern what a user is allowed to enter in an input field.
  • You have to enter data easily in a certain format and in a fixed-width input.
  • You have to enter input such as a date, time, phone number,  serial number, ISBN, or product activation key.

Do not use mask input if:

  • The mask prevents users from entering essential data.
  • The users need to enter data in a format other than the one used by the mask (for example, if users have to enter a phone number with a format for a different region).

Responsiveness

Mask input extends the input control (sap.m.Input) and has all the normal properties of an input field.

Components

The mask input control has a fixed length format to which the user’s input must conform. This can be particularly useful when the user needs to enter text or numbers with specific formatting, such as a phone number, postal code, or credit card number.

Mask input or a placeholder text are not substitutes for the input label. Using a label is mandatory. Placeholder texts in an input field are optional. Note that if there is no placeholder text, the input field will initially look empty. The mask formatting is revealed as soon as the focus is on the field.

It is possible to add additional descriptive texts to the input field (a unit of measurement, for example) by using a new association in the sap.m.InputBase control called ariaDescribedByThe association is responsible for referencing the elements that describe the control.

Mask input without placeholder text
Mask input without placeholder text
Mask input with placeholder text
Mask input with placeholder text

Immutable Characters

When defining the mask format, the developer can place immutable characters, such as brackets and dashes, in specific positions. The format also specifies the range of valid characters for each separate position, thus preventing the user from entering invalid input.

For example, when the user enters a phone number, the area code in brackets and the space between the numbers are already present.

Note that the sap.m.MaskInput control extends sap.m.Input and has all the normal properties of an input field.

When creating a new mask, the developer can change the configuration of some default properties. For example, the default placeholder symbol “_” can be changed to something else.

Behavior and Interaction (incl. Gestures)

Entering Text

  • Mask string appears in the input field on focus.
  • The default placeholder symbol is “_” and can be changed to something else.
Entering text into a mask input
Entering text into a mask input

Copying and Pasting

Copying to a mask input field:

Users can copy both formatted and unformatted strings into a mask input field. When the texts are pasted, they take on the format defined for the mask input field.

Example: Mask input field for a number with the format:  (000) 000 000000

Copied source string Value in mask input field after pasting
(555) 333 123456 (555) 333 123456
555-333-123456 (555) 333 123456
555 (333) 12 34 56 (555) 333 123456

Copying from a mask input field:

If you copy a string from a mask input field and paste it elsewhere, the format of the mask input field is copied as well.

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.

Deleting Content

Deleting a character from the string leaves the input information unchanged, except for the deleted character, which is replaced by a placeholder. (The mask does not shift if a character is deleted.)

Deleting individual characters in mask input
Deleting individual characters in mask input

Select the entire string and delete it. The placeholders will reappear.

Deleting all characters in mask input
Deleting all characters in mask input

Guidelines

Validation Rules

Another option is to define new validation rules, such as allowing lowercase characters from “a” to “e” only. This is particularly flexible because these rules are defined with regular expression syntax.

The mask comes with two predefined validation rules: one for all characters in the English alphabet, and one for the numbers from zero to ten.

Therefore, when the mask format is being defined, the alphabetic rule is represented by the letter “a”, and the numeric rule by the number “9”. For example, a numeric mask format with a length of five characters would be specified as “99999”, a mask that accepts only alphabetical characters would be specified as “aaaaa”, and a mixed mask could be “aaa99”. In the mixed mask example, the user would not be able to enter numeric characters anywhere other than in the last two positions.

When you create the MaskInput instance, you can specify the following settings:

  • Mask: The format specification, such as (123) 999-999.
  • PlaceholderSymbol: A single character used to represent empty positions in a mask value, such as _ _ _ _ _.
  • Rules: A collection of sap.m.MaskInputRule instances.

Unit of Measurement

You can use the layout options of the form to can add the unit of measurement (UoM) after the mask 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.

Properties

Mask string

The mask is defined by its character type (or by its length, as applicable). You should consider the following important facts:

  1. The mask characters normally correspond to an existing rule (one rule per unique character). Characters that do not are considered immutable characters. For example, the mask ‘2099’, where ‘9’ corresponds to a rule for digits, has ‘2’ and ‘0’ as immutable characters.
  2. Adding a rule that corresponds to the symbol placeholder is not recommended and would lead to unpredictable behavior.

Placeholder symbol string  “_”

This defines a placeholder symbol. It is shown in a position where there has not yet been any user input.

Resources

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

Elements and Controls

Implementation

Planning Calendar

The planning calendar allows users to see different appointments at the same time and to create new appointments. It allows the user to display appointments for several objects, such as a team calendar, and compare them to each other.

Usage

Use the planning calendar if:

  • You want to compare objects of the same type with each other over a period of time.
  • You require responsive behavior.
  • You have less than 100 lines in the calendar.

Do not use the planning calendar if:

  • You want to show a calendar for one object and a detailed overview of appointments over a long time interval.
  • You want to show a complex or graphical representation. In this case, please use the Gantt chart.
  • You have more than 100 lines in the calendar. In this case, please use the Gantt chart.

Responsiveness

In size S, the control provides pop-in behavior, which allows the user to see as many appointments as possible and to connect them with the corresponding object. If the toolbar contains too many actions for the space available, the overflow icon appears.

The interval section displaying the hours, days, and months is responsive and shows 12 values in size L, 8 values in size M, and 6 values in size S. You can override this behavior, but you should then check that the responsiveness is still working.

Planning calendar - Size L
Planning calendar - Size L
Planning calendar - Size M
Planning calendar - Size M
Planning calendar - Size S
Planning calendar - Size S

Types

You can define what size of interval the calendar should show, and whether multi selection should be possible. Additionally, the row header and the interval appointments are optional.

The control allows multi-select mode to be shown for the list items. This can be used, for example, to delete multiple objects from the view.

An app development team must decide whether to show the planning calendar with or without multi-select mode, or whether users should be able to switch between the two modes. Hiding the interval appointments of every object is optional.

The planning calendar can also be used without a row header. In this case, the row header disappears and only the appointments are visible. It can be used to show the calendar of one object. Note that the control was built mainly to compare time slots of different objects. For this reason, the time axis is shown horizontally and, depending on the interval, the appointments might shrink to smaller size. In this case, the text is cut off rather than truncated.

Components

This section describes the various components of the planning calendar.

Parts of the planning calendar
Parts of the planning calendar

The control consists of different parts:

  1. Header
  2. Toolbar
  3. View switch
  4. Navigation
  5. Time strip for hours/days/months
  6. Row header
  7. Row
  8. List item
  9. Interval appointment
  10. Appointment

1. Header

The header contains the toolbar and the navigation.

2. Toolbar

The toolbar consists of the calendar title (optional) and the toolbar actions, including a default view switch. You can add generic and app-specific actions that are relevant for your use case (such as creating an appointment, search, settings, showing the calendar legend, and so on). Always place actions that affect the entire calendar in the toolbar.

For more information, check out the toolbar guideline article.

The generic actions are as follows:

Search
Create Appointment
Add New Contact (icon: add-contact)
Multi-Select Mode (icon: multi-select)
Legend (icon: legend)
Settings (icon: action-settings)
Full Screen (icon: full-screen/exit-full-screen)

3. View switch

The view switch allows the user to switch between different time intervals (calendar views). Depending on the number of available calendar views, the view switch can be a segmented button (four views or less) or a select control (five views or more).

The 1 Month view shows an entire month. On desktop devices, the 1 Month view always displays an interval of 31 days. When the displayed month is shorter (28, 29, 30 days), days from the following month are displayed. They have a different visual state and serve as navigation to the following month.

The 1 Month view has an additional style for half-column appointment distribution, which is mainly used to avoid overlapping. The property appointmentRoundWidth can be set to “HalfColumn” or “None” (default). Currently, the width of the appointment is always rounded to 12 hours.
Note: This property is also applied when the calendar interval type is Days and the view shows more than 20 days.

On size M and Size S, the 1 Month view is adaptive. It consists of a calendar and a list of appointments for the selected day.

If you offer the 1 Week view, we strongly recommend displaying a different number of days in the Days view (more or less than seven). Otherwise, the user might be confused, as navigation for the two views differs.

The default calendar views are Hours, Days, Months, 1 Week, and 1 Month. The app developer can choose which views to include, depending on the use case, and how many values are shown for each view. App developers can change the default number of values shown, but they should then ensure that the app is still responsive. The app developer can also create custom views.

Relative views

When you need to display a period that is not connected to a certain time/date, you can map the calendar to relative dates (in contrast to absolute dates, such as, “Week 1”, “Week 2”). For example, when you would like to divide the year into quarters.

The application developer specifies the names of the intervals in the time strip and the index picker, as well as the size of the interval. The index picker then configures how many days are in one interval. All this happens in the PlanningCalendarView, once the newly created relative property is set to “true”.

In addition, the application developer sets a minDate in the planning calendar, determining the start date of the relative views.

4. Navigation

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

5. Time strip for hours/days/months

The time strip reflects the selected view, and shows the hours, days or months that are currently visible. The first day of the week can be defined. If not defined, the default is taken from the current user locale.

In all views that show days (Days, 1 Week, 1 Month), you can display calendar weeks in an extra line below the time strip (property: showWeekNumbers).

6. Row header

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

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

7. Row

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

8. List item

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

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

9. Interval appointment

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

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

10. Appointment

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

There are four types of appointments:

  • Regular: Displayed in two rows. One-row display is also possible if the appointmentsReducedHeight property is set to “true”.
  • Half-size: Always displayed in one row, shows the title.
  • Large: Always displayed in three rows, also shows the description for each appointment (if available).
  • Automatic: The number of rows is determined automatically.
    Appointment Info Rows
    Title only 1 row
    Title + text
    or:
    Title + description
    2 rows
    Title + text + description 3 rows

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

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

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

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

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

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

Planning Calendar Legend

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

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

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

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

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

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

Guidelines
Ensure that colors are used consistently within your product area.

The Appointments section contains the color values for the available appointment types. The app developer has to define explicitly which color represents which type. The planning calendar legend does not take the color automatically from the planning calendar.

If combined appointments in the calendar are of the same type (in Months view), they take the color of that type. Combined appointments of different types are marked gray. We also recommend adding the gray color for mixed combined appointments to the Appointments section in the legend.

Planning calendar legend
Planning calendar legend
Developer Hint
To prevent waiting time, app developers should load the sap.ui.unified library.

Behavior and Interaction

To create an appointment, the user must trigger an action by clicking the Create button in the toolbar. You can also configure the control to create a new appointment when the user clicks directly on a row.

The user can click the appointment to see further details. The app development team must define what kind of information is then shown. For example, clicking an appointment can trigger a popover with detailed information.

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

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

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

View switch

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

Today

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

Back and forward navigation

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

Date picker

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

Snapping Header

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

Header snaps to top when scrolling down
Header snaps to top when scrolling down

Drag and Drop

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

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

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

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

Combined appointments and interval appointments are not draggable.

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop

Guidelines

Switching the Row Header

To enable end users to rearrange the planning calendar by switching the row header, you can implement a flexible row header. This is not done by the control and must be implemented by the app development team.

The list items in the row header can be a value of any attribute of an appointment. The appointment attributes are part of app-specific content, so they should be specified by the app development team. The control does not provide default attributes.

Our guideline is to use the select control in the place of the calendar title. The select control will contain all the attributes that can serve as the row header. When a different attribute is selected, the calendar is rearranged accordingly. You can also add a counter after the list items to indicate how many appointments fall into a specific group.

It is also possible to have both the calendar title and select control, in which case you should have first the title and then the select.

On small screen sizes, use select instead of the calendar title. If you want to keep the calendar title, place select in the overflow menu.

Resources

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

Elements and Controls

Implementation

Text Area

The text area is an input control that allows the user to enter several lines of text.

Usage

Use the text area if you want users to enter multiple lines of text. If you only want them to enter a single line of text, use the input field instead.

Responsiveness

You can set the maximum number of lines to be shown. The amount of text depends on the size of the screen. On smaller screens, the user can scroll down the text area to see the entire text. To indicate that the text continues, the control shows only half of the last line. This also applies for mobile devices.

Components

The text area allows the user to enter multiple lines of text.

Text area – Default
Text area – Default
Text area – While editing
Text area – While editing

You can also set a placeholder (input prompt), which is inherited from sap.m.InputBase; property: placeholder. The prompt text is displayed when the input field is empty.

Text area – With placeholder (input prompt)
Text area – With placeholder (input prompt)
Text area – Selected text
Text area – Selected text
Information
For information on how to manage leading and trailing white space (blanks) when copying and pasting text into input controls, see removing leading and trailing white space.

Behavior and Interaction

Entering and Removing Text

As soon as the user starts typing, the placeholder disappears. It appears again when the user removes all the content from the text area.

You can also limit the number of characters a user can enter. In this case, the text area prevents the user from adding more characters than the maximum value defined (property: maxLength).

Text area – Limited
Text area – Limited

Making Text Non-Editable

You can set the text area to non-editable (property: editable). This mode still allows the user to scroll to the text that is currently hidden.

Text area – Read only
Text area – Read only

Disabling Text

You can also set the text area to disabled. In this case, the user cannot edit or scroll (property: enabled).

Text area – Disabled
Text area – Disabled

Growing Behavior

The text area control offers a growing property. It gives the control the ability to automatically grow and shrink with its content while the user is typing.

The maximum height of the text area is configurable. Define the height to reflect the space where the control will be located.

Growing text area: The text is aligned to the top of the text area.
Growing text area: The text is aligned to the top of the text area.
Growing text area: As the user continues to type, a new line is added to the bottom of the text area.
Growing text area: As the user continues to type, a new line is added to the bottom of the text area.

Text Area Counter

General Information

If you have set a character limit for the text box (property: maxLength), you can use the text area counter to show a character count (remaining characters, characters over the limit).

To turn on the counter, set the property showExceededText to true. The user can then see all inserted characters, including those that are over the limit.

Basic Interactions

The number of characters allowed is displayed below the text area, aligned to the right. A label indicates how many characters are left.

When the characters used are over the limit:

  • Тhe user can continue typing
  • The value of the counter changes.
  • We recommend changing the text area to a warning state.

When the user pastes copied text, characters that are over the limit are selected automatically. The user can delete any excess characters by pressing Delete or Back on the keyboard (or virtual keyboard for phones and tablets).

Text area counter - Default state (within the limit)
Text area counter - Default state (within the limit)
Counter over the limit
Counter over the limit
Developer Hint
If the text area already has a value state and the text length exceeds the limit, the value states are displayed in the following order (highest to lowest priority):

  • Additional error state available: This results in a higher priority (error + warning = error). If an error state is set, the text area is shown in an error state. When the error is fixed, the text area returns to the warning state until the character count is within the limit.
  • Additional warning state available: An additional warning state has the same priority as the counter warning state (warning + warning = warning). The text area stays in the warning state until all of the issues are fixed. The warning state set by the developer has the higher priority.
  • Additional success state available: In this case, the warning state has higher priority (success + warning = warning). Once the text count is within the limit, the text area shows the success state.

Styles

As with any other input control, you can validate the fields and show the result as a value state of the control (property: valueState). Possible value states are error, warning, success, information, or neutral (none).

For more information, see How To Use Semantic Colors and Form Field Validation.

Text area – Warning state
Text area – Warning state
Text area – Error state
Text area – Error state
Text area - Success state (with thinner border)
Text area - Success state (with thinner border)
Text area - Information state
Text area - Information state

Guidelines

  • As with other input fields, use a label. For exceptions regarding label usage, see the Exceptions section of the Label article.
  • The placeholder does not substitute a label. It can be used to give an additional hint, but should not repeat the label in long format.
  • If you want to use the text area with a fixed text length (property: maxLength), for example, inside a form, use text beside the text area to count down the number of remaining characters while the user is typing.
  • If you are applying the growing behavior of the text area, bear in mind that its maximum height should not exceed the height of the screen.
  • As a display mode equivalent, consider using an expandable text.

Saving Forms with a Text Area Counter

If a text exceeds the limit for the text area, there are two options for saving the form:

  • The form can be saved, but only contains the text within the character limit. If you follow this approach, inform the user that only part of the text will be saved. In this case, we strongly recommend setting the text area state to “warning” to indicate that there is a problem with the text.
  • The form cannot be saved until the user edits the text and the character count is within the limit. In this case, we strongly recommend setting the text area state to “error”.

Properties

  • You can provide a width by specifying the average character width (property: cols).
  • You can define the height of the text area by specifying the number of lines of text (property: rows). You can also set the height of the text area (property: height), which overrides the rows property.
  • You can define the type of wrapping for the text area (property: wrapping) as soft, hard, or off.
  • sap.m.TextArea has a growing property that enables the height of the text area to change dynamically while the user is typing.
  • sap.m.TextArea can show a count for the number of permitted characters, and allow users to type/paste text over the limit (property: showExceededText). This property determines whether characters that exceed the character limit are visible.
    • If this property is set to false, the user is not allowed to exceed the number of characters set in the maxLength property.
    • If this property is set to true, characters exceeding the maxLength value are selected on paste, and the counter below the input field displays the number of characters that are over the limit.
  • To provide additional information for assistive technologies like screen readers, use ariaDescribedBy and ariaLabelledBy.

Resources

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

Elements and Controls

Implementation

Select Dialog

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

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

Usage

Use the select dialog if:

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

Do not use the select dialog if:

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

Responsiveness

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

Size S

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

Size M

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

Size L

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

Components

Dialog Header

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

Single selection

Select

Example: Select Product

Multi-selection

Select

Example: Select Products

Search

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

Info Toolbar

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

Selected :

Example: Selected Products: 2

Content

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

Button Toolbar

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

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

Behavior and Interaction

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

Single Select

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

Multi-Select

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

Search

The user can search items.

Resize and Drag Dialog

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

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

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

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

Guidelines

List Options

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

When using the select dialog for selecting filters: If you need to indicate that all items apply as filter options, provide All as an option and place it at the beginning of the list.

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

Search Behavior

Two types of search behavior are available:

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

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

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

Reset/Remember Selections

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

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

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

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

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

Infobar

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

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

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

Infobar States

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

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

“Clear” Button

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

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

Content

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

Resources

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

Elements and Controls

Implementation

P13n Dialog

Intro

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

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

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

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

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

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

Usage

Use the P13n dialog if:

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

Do not use the P13n dialog if:

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

Responsiveness

The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), it shows as a centered dialog. For size S (smartphones), it displays as a full screen dialog.

Size S – Columns
Size S – Columns
Size M
Size M
Size L
Size L

Components

The P13n dialog consists of four different tabs that can be used separately or combined, as required by the use case:

  • Sort
  • Filter
  • Group
  • Columns

App developers can add more tabs manually.

Behavior and Interaction

Columns

The Columns tab allows users to change the visible table columns and the order in which they are displayed.

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

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

Show/Hide

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

Reorder

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

Search

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

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

Sort

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

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

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

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

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

Filter

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

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

Column

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

Operator

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

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

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

Available operators:

String (Text)

  • between
  • contains
  • equal to
  • begins with
  • ends with
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Number

  • between
  • equal to
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Date

  • between
  • equal to
  • after
  • on or after
  • before
  • before or on

Boolean (true/false)

  • equal to

Value

The last field contains the value by which the selected column is filtered. The kind of input field that is provided depends on the data type of the selected column and the selected operator. For example, the value field for fixed or Boolean values could be a dropdown list, an input field with suggestions, or a date picker. You can also offer two or even more fields if the use case requires it.

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

Group

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

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

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

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

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

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

Resources

Elements and Controls

Implementation

Time Picker

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

When to Use

Use the time picker if:

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

Do not use the time picker if:

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

Components

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

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

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

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

Time Picker Popover

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

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

If the user has opted for the 12-hour format in the user settings, an AM/PM switch is also displayed.

If seconds are not relevant for the use case, you can remove the seconds field.

Components of the time picker popover
Components of the time picker popover

Hours Clock Face

Depending on the time format, the hours clock face shows 12 hours or 24 hours:

  • The 12-hour clock face shows only one circle.
  • The 24-hour clock face shows an additional inner circle for the times from 13:00 to 24:00 hours.
24-hour clock face
24-hour clock face

Minutes Clock Face

When the minutes value is selected in the time display, the minutes clock face is shown.

Minutes clock face
Minutes clock face

Seconds Clock Face

When the seconds value is selected in the time display, the seconds clock face is shown.

Seconds clock face
Seconds clock face

Behavior and Interaction

Users can enter the time in two ways:

  • Enter a time directly in the input field
  • Select a time using the time picker popover

Entering a Time in the Input Field

On desktop devices, the user selects the time input field and enters the time using the keyboard.

Entering a time directly
Entering a time directly

On tablet and mobile devices, selecting the time input field opens a time input popover. The user can then use the mobile keyboard to enter the time. For the 12-hour time format, the popover also offers an AM/PM switch.

1) Focus on time input field
1) Focus on time input field
2a) Time input popover, 24-hour format
2a) Time input popover, 24-hour format
2b) Time input popover, 12-hour format with AM/PM switch
2b) Time input popover, 12-hour format with AM/PM switch

Selecting a Time with the Time Picker Popover

By default, the time picker shows the hours clock face, and the hour value is highlighted in the time display at the top of the popover. On desktop devices, users can select the hour using a mouse or the keyboard arrows. Tablet and mobile device users can drag the handle around the dial to the desired number, or tap the number on the dial. The selected hour is then entered in the time display at the top.

When an hour value is set, the hours clock face automatically switches to the minutes view: the minutes clock face is shown and the minutes value is highlighted in the time display. If an hour was selected by mistake, the user can switch back to the hours clock face by selecting the hours value.

Minutes and seconds are selected in the same way.

Clicking the OK button confirms the selected time. Clicking Cancel or clicking anywhere outside the popover discards the changes.

Selecting time on a desktop device
Selecting time on a desktop device
Interaction options on mobile devices: Drag or tap
Interaction options on mobile devices: Drag or tap

Default Time

You can set a predefined time, which shows as the initial value in the time input field and the time picker popover. If you don’t set a default time at application level, the control defaults to the current time. Users can overwrite the initial value.

 

Preventing Errors

You can prevent users from making incorrect entries by only allowing certain characters (see mask input). If the user enters a time that has the correct format but is invalid (such as 12:60:85), the time picker displays a validation error (see input validation).

You can switch off the integrated mask input feature, but we strongly recommend using it. Only deactivate mask input if you need to make an exception for your use case (for example, if a variable length is required for a specific locale).

Style

The time picker has five basic value states:

  1. Regular
  2. Information
  3. Success
  4. Warning
  5. Error

For the information, warning, and error states, you can also display a message with additional information below the field.

Time picker value states
Time picker value states

Responsiveness

The time picker comes with a cozy mode and a compact mode. In the compact mode, the time input field and the button are smaller than in the cozy mode. For more information, see Content Density.

For mobile (size S) devices, the time picker popover does not open below the time input field, but in a subview.

Time picker on a desktop device
Time picker on a desktop device
Time picker on mobile (size S)
Time picker on mobile (size S)

Guidelines

Time Formats

Seconds

Only let the user select time in seconds if this information is really necessary.

Time Zone

If the user has to set a time that is time zone-sensitive, offer a select control next to the time picker control to choose the appropriate time zone.

For more information, see Formatting Time.

Properties

AM and PM are locale-dependent. You can set the locale with the property localeId.

You can define the display format for the time in the input field and at the top of the time picker popover (property: displayFormat). For more information about time formats, see Formatting Dates.

Related Links

Elements and Controls

Implementation

P13n Dialog

Intro

The p13n dialog control allows users to personalize one or more of the following table attributes:

  • Columns: Visibility and order of columns
  • Sort: Sort criteria for table items
  • Filter: Filter criteria for table items
  • Group: Grouping table items by specific attributes

These tabs can be shown in any combination, as required by the use case.

The P13n dialog is intended for complex tables that have a large number of columns and require complex queries for sorting, grouping, and filtering.
For simple tables, see the view settings dialog and table personalization dialog.

The P13n dialog is opened using the corresponding buttons on the right-hand side of the table toolbar.

Dialog buttons within the table toolbar
Dialog buttons within the table toolbar

Usage

Use the P13n dialog if:

  • Users can personalize more than ~20 columns.
  • You need multiple personalization functions (columns, sorting, filtering, grouping, …)
  • You are using the analytical table.
  • Complex queries have to be built for the table.

Do not use the P13n dialog if:

  • Users can personalize fewer than ~20 columns.
  • You only need a simple feature to show/hide columns.

Responsiveness

The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), it shows as a centered dialog. For size S (smartphones), it displays as a full screen dialog.

Size S – Columns
Size S – Columns
Size M
Size M
Size L
Size L

Components

The P13n dialog consists of four different tabs that can be used separately or combined, as required by the use case:

  • Sort
  • Filter
  • Group
  • Columns

App developers can add more tabs manually.

Behavior and Interaction

Columns

The Columns tab allows users to change the visible table columns and the order in which they are displayed.

The available columns are shown as list items with checkboxes. The checkboxes for the columns that are currently being displayed are selected.

The Show Selected / Show All button toggles the display between all columns and only those that are currently selected.

Show/Hide

To show or hide a column, users select or deselect the column checkbox.

Reorder

To change the order of the columns, users focus on a list item and use the buttons on the right-hand side of the table toolbar to move it up or down. The order of the columns from top to bottom corresponds to the order on the table from left to right.

Search

The search field in the table toolbar enables users to find a specific column more quickly. Matching columns are displayed as soon as the user starts to type.

Column settings in the P13n dialog
Column settings in the P13n dialog

Sort

On the Sort tab, the user can specify the sort criteria and sort order (ascending or descending).

Each entry has two input fields: one for choosing the sort column, and one for choosing the sort order.

Users can enter multiple sort criteria. Once a sort criterion is entered, a new line appears for entering another one.

The order of the sort criteria reflects the order in which they are applied to the table.

Sort settings in the P13n dialog
Sort settings in the P13n dialog
Information
Using the sort feature for column headers replaces ALL sort options in the dialog!

Filter

The Filter tab allows users to filter the table information according to specific criteria.

Users can add filters with the Add button or remove them by clicking the  (Remove Filter) icon at the end of each filter item.

Column

In the first input field, the user selects the column to be filtered. Any column can be selected, including columns that are not currently visible.

Operator

The second field contains the operator that is applied to the filter value (such as greater than or not before).

To include or exclude filter criteria, the user selects the relevant operator from the Include or Exclude section of the dropdown list. For example, equal to to include a value, and not equal to to exclude it.

If individual filter criteria have Boolean values, the operator is always “equal to” and the operator dropdown is disabled.

Available operators:

String (Text)

  • between
  • contains
  • equal to
  • begins with
  • ends with
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Number

  • between
  • equal to
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Date

  • between
  • equal to
  • after
  • on or after
  • before
  • before or on

Boolean (true/false)

  • equal to

Value

The last field contains the value by which the selected column is filtered. The kind of input field that is provided depends on the data type of the selected column and the selected operator. For example, the value field for fixed or Boolean values could be a dropdown list, an input field with suggestions, or a date picker. You can also offer two or even more fields if the use case requires it.

Information
If there is a filter bar, use the filter bar functionality and deactivate the filter feature of the P13n dialog.

Group

The Group tab can be used to group the table data.

In the selection field, the user can select a grouping criterion from a list of all available columns.

For analytical tables, users can define more complex grouping scenarios. Once a grouping criterion is entered, a new line appears for entering another one. In addition, the Show Field As Column checkbox allows users to decide whether or not to display the corresponding column.

The grouped table shows the individual values for the selected field as the group headers. Expanding the group shows all the corresponding table items.

If you have defined multiple groups, the grouped table shows the individual values for the first selected field. Expanding the groups shows the subgroups and items in an expandable hierarchy.

Warning
To group by a specific column, that particular column must be marked as visible on the Columns tab!
Group tab in the P13n dialog
Group tab in the P13n dialog

Guidelines

On the table toolbar, offer separate buttons for each personalization function (sort, filter, group, column settings).

With each button, open the P13n dialog with just the corresponding tab. Do not display the other tabs.

Resources

Elements and Controls

Implementation

Upload Set

The upload set control allows users to upload single or multiple files from a device (desktop, tablet, or phone) to an SAP Fiori app.

Despite its name, the upload set is not limited to plain upload scenarios. Depending on the context or the access rights, some users may only be allowed to download the files uploaded by others. You can use the upload set control for both cases.

When to Use

Use the upload set control if:

  • You want to show a list of uploaded files that can be modified.
  • You want to allow users to add or remove several files, and to change the file names.
  • You are still using one of the older upload controls:
    • sap.ca.ui.FileUpload
    • sap.m.UploadCollection (deprecated since SAPUI5 version 1.88)

Do not use the upload set control if:

  • The user can upload only one file to the app. In this case, use the sap.ui.unified.FileUploader control instead.

Layout

Default Layout and Actions

Files are listed vertically. By default, each item has an Edit and a Remove button.

While most file types have generic icons (for example documents, spreadsheets, or presentations), image files have a small thumbnail preview.

You can control the visibility and the active state for all actions at item level.

Layout – Items
Layout – Items

Attributes and Statuses

You can display additional attributes and statuses below the file name. Attributes can include the name of the person who uploaded the file, the upload date, the version number, file size, and so on.

You can also define your own statuses. These usually refer to the object state in a workflow (such as Approved or Overdue). Statuses can be shown in different colors in accordance with the visual guideline for semantic colors.

If multiple attributes or statuses are displayed, they are separated by a bullet.

Layout – Attributes and statuses
Layout – Attributes and statuses

Technical Statuses

Unlike the statuses mentioned above, technical statuses are not bound to a workflow or business process. They are mainly used to show the current editing status of an object (Draft, Locked, Unsaved Changes). For further uses and more details, see Object Display Components and Draft Handling.

Layout – Technical statuses
Layout – Technical statuses

Behavior and Interaction

Uploading Files

The upload set offers two basic working modes:

  • Instant upload (default): Files are uploaded as soon as they are dropped onto the control or the OK button in the file selection dialog is clicked.
  • Manual upload: All added files are first collected in the front-end list, where the user needs to trigger the upload.
Developer Hint
Using the Boolean property instantUpload, you can determine whether files are uploaded immediately or whether the user needs to trigger the upload explicitly.

If some users are only allowed to download the files uploaded by others, you can disable the upload option.

Developer Hint
The Boolean property uploadEnabled controls whether or not users are able to upload files.

Unlike the deprecated Upload Collection control, the Upload Set control allows you to use a custom uploader.

Developer Hint
For an example of a custom uploader, see the SAPUI5 sample.

Empty State

If empty, the upload set provides a hint to use the Upload button or drag and drop to upload files. This hint already provides a large enough zone for users to drop their files.

Interaction - No files found
Interaction - No files found

Drag and Drop

Users can easily select one or multiple files from their computer and drag them onto the upload set to start the upload.

As soon as a user starts to drag a file over the application, the hint changes into a drop zone, indicating where to place the file.

Interaction - Drag and drop (1)
Interaction - Drag and drop (1)

As the user hovers over the drop zone, the color changes again to indicate that the file can be released.

The upload process itself is the same as if a file had been added via the Upload button.

Interaction - Drag and drop (2)
Interaction - Drag and drop (2)

Opening Files

Files are opened by clicking the file name of the attachment. How the files open depends on the operating system and browser settings.

On desktop devices, clicking the file name opens the program that has been assigned to this file type. In some cases, the files are opened directly in the browser if they are among the supported file types, like jpg, png or pdf. However, this also depends on the individual browser and its settings.

Mobile devices usually open a dialog in which the user can select an app that supports this file type.

Renaming Files

The Edit function works identically on desktop and mobile devices.

  1. The user clicks the Edit ) button.
  2. The file name becomes an input field in which the existing name is highlighted. The icon buttons Edit (  ) and Remove (  ) are replaced by two text buttons: Rename and Cancel.
  3. When the user starts typing, the highlighted text is overwritten. Alternatively, the user can use the mouse or keyboard to change the selected text.
  4. The new file name can be validated in two ways:
    • The user clicks Rename.
    • The user presses Enter.
Guidelines
Specify the file name in the dialog.

Removing Files

The Remove function works identically on desktop and mobile devices.

After clicking the Remove (  ) button for a file, the user is prompted to confirm the removal of the respective file.

Remove confirms the deletion and the file is removed from the list. Cancel aborts the process, closes the dialog, and brings the user back to the file list without making any changes.

Clickable Attributes

Object attributes can be made clickable. This can be very helpful to provide users with a direct way to access certain information, such as a person’s profile and contact data, or the version history of a file.

Examples:

  • Uploaded By: John Miller
  • Last Edited By: Donna Moore
  • Version 1.1
Guidelines

  • Use a quick view to show this additional information.
  • Don’t use more than two or three linked attributes per item. Excessive use of clickable attributes overloads the UI with interactive elements and has a negative impact on usability.

Responsiveness

The upload set control offers full responsive behavior from small phones to large desktop screens. Uploading, downloading, renaming, and deleting works on all screen sizes. Texts that no longer fit into the available space are truncated.

Size S
Size S
Size M
Size M
Size L
Size L

Example

You can use the upload set control in different contexts, whenever users need to be able to upload multiple files. The example below shows the object page of a product, in this case a machine, with an Attachments tab containing several documents about its documents for assembly, service, and warranty.

Upload set in object page
Upload set in object page

Other possible scenarios:

  • Warranty claim: Users need to upload images of a damaged item.
  • Product details: Editors can upload product pictures that will be shown in the online shop.
  • Service history: Whenever maintenance measures are performed, the service worker attaches a document to the object.

Top Tips

When to Show, Disable, and Hide Actions

The Edit and Remove buttons are visible and enabled by default. If you don’t want to allow users to edit or remove uploaded files, hide the corresponding buttons.

Don’t leave buttons enabled and then show an error message when the function isn’t available.

Do
Vertically align all actions
Vertically align all actions
Don't
Don't position buttons differently. Place identical actions directly underneath one another.
Don't position buttons differently. Place identical actions directly underneath one another.
Do
If users aren't allowed to use a certain function, hide the corresponding button.
If users aren't allowed to use a certain function, hide the corresponding button.
Don't
Don't disable all actions. If users aren't allowed to use a certain action, don't show the corresponding button.
Don't disable all actions. If users aren't allowed to use a certain action, don't show the corresponding button.
Do
If an action is unavailable, disable it (for example, if a file was uploaded by another user).
If an action is unavailable, disable it (for example, if a file was uploaded by another user).

Custom Uploader

Developer Hint
Unlike the deprecated Upload Collection control, the Upload Set control allows you to implement a custom uploader.

Related Links

Elements and Controls

Implementation

Upload Set

The upload set control allows users to upload single or multiple files from a device (desktop, tablet, or phone) to an SAP Fiori app.

Despite its name, the upload set is not limited to plain upload scenarios. Depending on the context or the access rights, some users may only be allowed to download the files uploaded by others. You can use the upload set control for both cases.

When to Use

Use the upload set control if:

  • You want to show a list of uploaded files that can be modified.
  • You want to allow users to add or remove several files, and to change the file names.
  • You are still using one of the older upload controls:
    • sap.ca.ui.FileUpload
    • sap.m.UploadCollection (deprecated since SAPUI5 version 1.88)

Do not use the upload set control if:

  • The user can upload only one file to the app. In this case, use the sap.ui.unified.FileUploader control instead.

Layout

Default Layout and Actions

Files are listed vertically. By default, each item has an Edit and a Remove button.

While most file types have generic icons (for example documents, spreadsheets, or presentations), image files have a small thumbnail preview.

You can control the visibility and the active state for all actions at item level.

Layout – Items
Layout – Items

Attributes and Statuses

You can display additional attributes and statuses below the file name. Attributes can include the name of the person who uploaded the file, the upload date, the version number, file size, and so on.

You can also define your own statuses. These usually refer to the object state in a workflow (such as Approved or Overdue). Statuses can be shown in different colors in accordance with the visual guideline for semantic colors.

If multiple attributes or statuses are displayed, they are separated by a bullet.

Layout – Attributes and statuses
Layout – Attributes and statuses

Technical Statuses

Unlike the statuses mentioned above, technical statuses are not bound to a workflow or business process. They are mainly used to show the current editing status of an object (Draft, Locked, Unsaved Changes). For further uses and more details, see Object Display Components and Draft Handling.

Layout – Technical statuses
Layout – Technical statuses

Behavior and Interaction

Uploading Files

The upload set offers two basic working modes:

  • Instant upload (default): Files are uploaded as soon as they are dropped onto the control or the OK button in the file selection dialog is clicked.
  • Manual upload: All added files are first collected in the front-end list, where the user needs to trigger the upload.
Developer Hint
Using the Boolean property instantUpload, you can determine whether files are uploaded immediately or whether the user needs to trigger the upload explicitly.

If some users are only allowed to download the files uploaded by others, you can disable the upload option.

Developer Hint
The Boolean property uploadEnabled controls whether or not users are able to upload files.

Unlike the deprecated Upload Collection control, the Upload Set control allows you to use a custom uploader.

Developer Hint
For an example of a custom uploader, see the SAPUI5 sample.

Empty State

If empty, the upload set provides a hint to use the Upload button or drag and drop to upload files. This hint already provides a large enough zone for users to drop their files.

Interaction - No files found
Interaction - No files found

Drag and Drop

Users can easily select one or multiple files from their computer and drag them onto the upload set to start the upload.

As soon as a user starts to drag a file over the application, the hint changes into a drop zone, indicating where to place the file.

Interaction - Drag and drop (1)
Interaction - Drag and drop (1)

As the user hovers over the drop zone, the color changes again to indicate that the file can be released.

The upload process itself is the same as if a file had been added via the Upload button.

Interaction - Drag and drop (2)
Interaction - Drag and drop (2)

Opening Files

Files are opened by clicking the file name of the attachment. How the files open depends on the operating system and browser settings.

On desktop devices, clicking the file name opens the program that has been assigned to this file type. In some cases, the files are opened directly in the browser if they are among the supported file types, like jpg, png or pdf. However, this also depends on the individual browser and its settings.

Mobile devices usually open a dialog in which the user can select an app that supports this file type.

Renaming Files

The Edit function works identically on desktop and mobile devices.

  1. The user clicks the Edit ) button.
  2. The file name becomes an input field in which the existing name is highlighted. The icon buttons Edit (  ) and Remove (  ) are replaced by two text buttons: Rename and Cancel.
  3. When the user starts typing, the highlighted text is overwritten. Alternatively, the user can use the mouse or keyboard to change the selected text.
  4. The new file name can be validated in two ways:
    • The user clicks Rename.
    • The user presses Enter.
Guidelines
Specify the file name in the dialog.

Removing Files

The Remove function works identically on desktop and mobile devices.

After clicking the Remove (  ) button for a file, the user is prompted to confirm the removal of the respective file.

Remove confirms the deletion and the file is removed from the list. Cancel aborts the process, closes the dialog, and brings the user back to the file list without making any changes.

Clickable Attributes

Object attributes can be made clickable. This can be very helpful to provide users with a direct way to access certain information, such as a person’s profile and contact data, or the version history of a file.

Examples:

  • Uploaded By: John Miller
  • Last Edited By: Donna Moore
  • Version 1.1
Guidelines

  • Use a quick view to show this additional information.
  • Don’t use more than two or three linked attributes per item. Excessive use of clickable attributes overloads the UI with interactive elements and has a negative impact on usability.

Responsiveness

The upload set control offers full responsive behavior from small phones to large desktop screens. Uploading, downloading, renaming, and deleting works on all screen sizes. Texts that no longer fit into the available space are truncated.

Size S
Size S
Size M
Size M
Size L
Size L

Example

You can use the upload set control in different contexts, whenever users need to be able to upload multiple files. The example below shows the object page of a product, in this case a machine, with an Attachments tab containing several documents about its documents for assembly, service, and warranty.

Upload set in object page
Upload set in object page

Other possible scenarios:

  • Warranty claim: Users need to upload images of a damaged item.
  • Product details: Editors can upload product pictures that will be shown in the online shop.
  • Service history: Whenever maintenance measures are performed, the service worker attaches a document to the object.

Top Tips

When to Show, Disable, and Hide Actions

The Edit and Remove buttons are visible and enabled by default. If you don’t want to allow users to edit or remove uploaded files, hide the corresponding buttons.

Don’t leave buttons enabled and then show an error message when the function isn’t available.

Do
Vertically align all actions
Vertically align all actions
Don't
Don't position buttons differently. Place identical actions directly underneath one another.
Don't position buttons differently. Place identical actions directly underneath one another.
Do
If users aren't allowed to use a certain function, hide the corresponding button.
If users aren't allowed to use a certain function, hide the corresponding button.
Don't
Don't disable all actions. If users aren't allowed to use a certain action, don't show the corresponding button.
Don't disable all actions. If users aren't allowed to use a certain action, don't show the corresponding button.
Do
If an action is unavailable, disable it (for example, if a file was uploaded by another user).
If an action is unavailable, disable it (for example, if a file was uploaded by another user).

Custom Uploader

Developer Hint
Unlike the deprecated Upload Collection control, the Upload Set control allows you to implement a custom uploader.

Related Links

Elements and Controls

Implementation

Select Dialog

The select dialog enables users to select one or more items from a comprehensive list. The select dialog comes with a list of entries and a search field to filter the list.

A more enhanced dialog for single selection and multiselection is the value help dialog as it offers range selection and excluding functions.

Usage

Use the select dialog if:

  • Users need to select one or more entries from a comprehensive list that contains multiple attributes or values.

Do not use the select dialog if:

  • Users need to pick one item from a predefined set of options that contains one attribute or value only such as languages. In this case, consider using the combo box or select instead.
  • Your use case requires more enhanced functionalities such as a selection based on ranges. For the selection of values, consider using the value help dialog instead.
  • Your use case requires tabs, filters, or an Add New functionality in the select dialog. In this case, use a standard dialog instead.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

The display of the select control depends on the device. On phones, the selection list takes up the whole screen. On desktop and tablet devices it appears as a popover.

Size S

Single select dialog in full screen on smartphone
Single select dialog in full screen on smartphone
Multi-select dialog in full screen on smartphone
Multi-select dialog in full screen on smartphone

Size M

Single select dialog on tablet
Single select dialog on tablet
Multi-select dialog on tablet
Multi-select dialog on tablet

Size L

Single select dialog on desktop
Single select dialog on desktop
Multi-select dialog on desktop
Multi-select dialog on desktop

Components

Dialog Header

You need to set the title of the dialog header (1). We recommend the following form:

Single selection

Select

Example: Select Product

Multi-selection

Select

Example: Select Products

Search

The first element in the dialog is a standard search field (2).

Info Toolbar

The info toolbar (3) is only available in multi-selection mode. It shows the number of selected items in the following form:

Selected :

Example: Selected Products: 2

Content

The content area (4) can be filled with any list content inherited from the list item base, such as standard list items, display list items, and feed list items. You can set the content to be displayed as grouped.

Button Toolbar

The button toolbar (5) contains two buttonsSelect and Cancel. Select takes over the selection, while Cancel resets the selection to the state it was in when the dialog was opened.

Components of the select dialog. Left: single select, right: multi-select
Components of the select dialog. Left: single select, right: multi-select

Behavior and Interaction

The select dialog can be called from any control. The most common trigger is an input field with a selection icon, also known as a “value help field”, or F4. Alternative triggers are buttons or icons, which add items to an existing list.

Single Select

Once users select an entry, the select dialog is closed and the selected entry is taken over. If applicable, the entry is displayed in the field from which the dialog was triggered.

Multi-Select

In the multi-select version of the select dialog, checkboxes are provided for choosing multiple entries. The selection is taken over when the user closes the dialog via OK. Cancel closes the dialog without taking over the selected values. An infobar indicates the number of selected items.

Search

The user can search items.

Resize and Drag Dialog

You can make the select dialog resizable and draggable by setting the corresponding properties (also called resizable and draggable) to “true”.

A resizable dialog makes sense if the items inside have long names or descriptions.

A draggable dialog allows users to see the app content behind the dialog.

Guidelines
Both features are optional. However, even if you only need one, always set both of them to “true” to ensure consistency.

Guidelines

List Options

If you need to indicate that none of the selection options are selected, or you need to allow the user not to select an option, provide (None) as an option and place it at the beginning of the list.

If you need to indicate that all items apply (for example, as a list filter), provide All as an option and place it at the beginning of the list.

Select list with '(None)'
Select list with '(None)'

Search Behavior

Two types of search behavior are available:

(1) A live search, also known as “search-as-you-type” (property: liveChange), which is triggered by each character that the user enters or deletes.

(2) A manual search, which is triggered explicitly after the user enters text in the search field and clicks the Search icon or presses the ENTER key.

Although app developers need to decide themselves which search to use, we recommend implementing the live search whenever possible. Use the manual search only if the amount of data is too large and your app would otherwise run into performance issues. For more information, check out the article on search.

Reset/Remember Selections

By default, the selection is reset when the dialog is closed. This allows users to make a new selection when they reopen the dialog and makes sense when users need to add multiple items to a table.

Selection is reset after the dialog is closed
Selection is reset after the dialog is closed

However, if your use case requires selections in a dialog to be remembered so that the user can make corrections, you can set the rememberSelections function in the select dialog to “true”. When users exit the dialog by clicking Cancel, the selection is then restored to the state it was in when the dialog was opened.

Selection is remembered after the dialog is reopened
Selection is remembered after the dialog is reopened

This also works in single-select dialogs. There, if users click the remembered item again, the dialog closes and they do not have to explicitly click Cancel.

Infobar

In multi-selection mode, an infobar shows the number of selected items. Use the following format:

Selected: [Number of selected items]
Example: Selected: 2

Note that the infobar is not “sticky”. When the user scrolls down the list, the infobar scrolls off the screen.

Infobar States

The infobar has two states – active and non-active (non-clickable). For more information see Infobar States.

Infobar - Active state
Infobar - Active state
Infobar - Non-active state
Infobar - Non-active state

“Clear” Button

The Clear button allows users to clear all the selected items. By default, the button is not shown. To display the button, set the showClearButton property to “true”.

Select dialog with 'Clear' button
Select dialog with 'Clear' button

Content

By default, the select dialog comes with a growing feature (property: growing = “true”). We recommend disabling the growing feature and setting this property to “false”. This ensures that all items in the table are loaded at once, and that the “Items selected” count, the search, and select/deselect features all work properly.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Multi-Input Field

A multi-input field allows the user to enter multiple values, which are displayed as tokens. To help the user enter a valid value, you can enable the suggestions feature and the value help option.

Usage

Use the multi-input field if:

  • You want the user to select multiple ranges (with the value help option and the value help dialog).
  • The dataset to choose from is expected to increase over time (for example, to more than 200 values).
  • You need to provide the value help option to help users select or search multiple business objects.
  • You want to enable users to add custom values.

Do not use the multi-input field if:

  • You want the user to select one entry only. In this case, use the input field or combo box instead.
  • You want the user to select from a pre-defined set of options only. In this case, use the multi-combo box instead.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

Size S

  • Cozy mode.
  • When the user clicks the multi-input field, a new full screen dialog opens. After clicking the input field and typing, the suggestions can be selected. When the user makes a selection, the dialog closes and the token is displayed.
  • The user can review the tokens by swiping them to the left or right.
Multi-input field (size S)
Multi-input field (size S)
Suggestions on a smartphone (size S)
Suggestions on a smartphone (size S)

Size M

  • Cozy mode.
  • The suggestions appear below or above the multi-input field.
  • The user can review tokens by swiping them to the left or right.
Suggestions on a tablet (size M)
Suggestions on a tablet (size M)

Size L

  • Compact mode.
  • The suggestions appear below or above the multi-input field.
  • The user can review tokens by pressing the right or left arrows on the keyboard.
Suggestions on a desktop device (size L)
Suggestions on a desktop device (size L)

Types

The input types of the multi-input field are identical to those of the input field.

Behavior and Interaction

Adding Tokens

A token can be added using suggestions or value help. As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. The user can accept the autocompleted value by pressing ENTER. The autocomplete property is set by default if suggestions are available, but can also be switched off.

When an item is selected from the suggestions dropdown, the corresponding token is created, and the input field is ready for the next entry. Tokens are placed next to each other on one line.

The suggestions dropdown can be wider than the input field itself, but not wider than the current browser window.

Warning
The typeahead input feature is not available for Android devices.
Developer Hint
Values that are entered can also be tokenized when the user presses ENTER. The app development team can perform a custom validation of the entered data and decide whether a token should be created.
A token in a multi-input field
A token in a multi-input field
A multi-input field with two tokens while editing
A multi-input field with two tokens while editing
Information
For information on how to manage leading and treading whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Reviewing Tokens

If tokens have been selected, and the input field is not in focus, the input field displays as many tokens as possible in the available space. If more tokens have been selected, an [n] More label indicates the number of hidden tokens. The tokens in the input field appear in the order in which they were selected.

Clicking the [n] More label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its delete icon.

Multi-input field - 'n More' label (desktop)
Multi-input field - 'n More' label (desktop)
More items displayed (desktop)
More items displayed (desktop)
More items displayed (phone)
More items displayed (phone)

If the length of the last selected token exceeds the width of the input field, a label [n] Item/s is shown when the field is not in focus.

Clicking the [n] Item/s label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its delete icon.

If there is only one token in the input field and its length exceeds the width of the input field, the text is truncated. Clicking the token opens a popover below the input field, in which the full text of the token is shown.

Multi-input field - '1 Item' case (desktop)
Multi-input field - '1 Item' case (desktop)
Showing the compete item
Showing the compete item
Multi-input field - 'n Items' label (desktop)
Multi-input field - 'n Items' label (desktop)
Displaying all items
Displaying all items

In the input field itself, the user can review tokens using the left or right cursor keys on a desktop, or by swiping to the left or right on a smartphone or tablet. Tokens can be selected by either clicking/tapping them or by pressing Space (selects the focused token).

Selected token
Selected token

Deleting Tokens

The user can delete tokens by pressing the Backspace or Del button (when selected) on a desktop’s keyboard, or by tapping the Delete icon on a mobile device.

Using Value Help

You can enable the value help option to provide a more advanced dialog for finding the relevant business object. Two dialogs can be used at present:

Value help icon on empty multi-input field
Value help icon on empty multi-input field
Select Dialog
Select Dialog
Selecting Items
Selecting Items
Displaying the selected items in the multi-input field
Displaying the selected items in the multi-input field
Value help icon on empty multi-input field
Value help icon on empty multi-input field
Value help dialog
Value help dialog
Selecting Items
Selecting Items
Displaying the selected items in the multi-input field
Displaying the selected items in the multi-input field

To give a better indication of the type of data that can be selected, you can exchange the value help icon.

Custom value help icon
Custom value help icon

Filtering

When the user starts typing in the input field, the list is filtered. Only items that match the character or characters entered are shown in the dropdown list. The default filtering method is “starts with per term”, which matches the beginning of each word in an item’s text.

In addition, application developers can set a custom filtering method “starts with” or “contains” (method: setFilterFunction). The “starts with” approach filters only for items where the beginning of the label matches the query entered. The “contains” approach searches the full label for a match.

As a visual hint for the user, the matched characters are highlighted (bold) in the option list items. The highlighting works on the basis of “starts with per term”, regardless of the filtering method.

Multi-input field - Default filtering, autocomplete in the input field is switched off
Multi-input field - Default filtering, autocomplete in the input field is switched off

Copying and Pasting Data from a Spreadsheet or Text File

The multi-input field can handle paste actions containing multiple items, such as items that have been selected in a column of a spreadsheet or text file. The user simply selects a whole column in the spreadsheet, copies it, and then pastes it from the clipboard into the multi-input field. Each item is represented as a token. If a single value is copied and pasted into the field, it is shown as a text value, as further editing might be required before it is converted into a token.

Grouping

You can group the items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

The column headers within the tabular suggestion list remain in place when the list is scrolled (“sticky” behavior).

Multi-input with grouped suggestions
Multi-input with grouped suggestions
Multi-input with grouped tabular suggestions
Multi-input with grouped tabular suggestions
Multi-input field with grouped tabular suggestions making use of the table's pop-in behavior
Multi-input field with grouped tabular suggestions making use of the table's pop-in behavior

Due to a technical limitation, the group headers are not visible when clicking on the n More text. 

Styles

The following images show how the states of the multi-input field are styled.

Unselected
Unselected
Unselected with predefined placeholder
Unselected with predefined placeholder
Unselected on hover
Unselected on hover
In focus
In focus
Selected items shown as tokens
Selected items shown as tokens
Expanded multi-selection
Expanded multi-selection

When an error, warning, or information value state is displayed, the details can be provided as text. The text is shown when the corresponding control has the focus. In addition to plain text, you can include one or several links.

Error
Error
Warning
Warning
Success
Success
Information
Information

For details on the different states, see UI Element States.

For more information on semantic colors for value states, see How to Use Semantic Colors.

Guidelines

  • Give the control a width that is appropriate for the range of values that are going to be entered. Try to avoid setting a fixed width on this control. Instead, embed it in a proper layout (such as a form, simple form, or grid layout) and work with the layout data property.
  • Provide meaningful labels for all input fields. Do not use the placeholder as a replacement for the label. The placeholder should only provide an additional hint.
  • The multi-input field can currently contain tokens and one free text value. If you allow only validated values, display an error or warning when the user tries to leave the field to indicate that the value entered is invalid, or remove the value.
  • If users try to select an item that has been selected before, we recommend setting an error state and providing a meaningful message.
Multi-input - Error state for an item that has already been selected
Multi-input - Error state for an item that has already been selected
  • You can use the layout options of the form to add the unit of measurement (UoM) after the multi-input control. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.
Developer Hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

  • The multi-input field can be used in the grid tableanalytical table and tree table as well, as condensed mode is already supported, both for desktop and mobile (tablets).
Multi-input field in the grid table in condensed mode
Multi-input field in the grid table in condensed mode
  • In display mode, use a text. Show the texts of the tokens, separated by bullet points. Provide an overflow for all texts that do not fit in one line.
Recommend display-mode equivalent
Recommend display-mode equivalent
Recommended display-mode equivalent with overflow indicator
Recommended display-mode equivalent with overflow indicator
Recommended display mode equivalent with overflow opened
Recommended display mode equivalent with overflow opened

Properties

Since the multi-input field is derived from the input field, refer to the properties in the input field article.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Date Range Selection

The control for selecting the date range is a single-field input control. Users can enter a localized date range using touch, mouse, or keyboard input, or by selecting a date range in the calendar. They can also navigate directly from one month or year to another.

Usage

Use the date range selection if:

  • You need a time range and know that your user is a power user who has to input lots of data. If the keyboard is the primary device used for navigating the app, use two input fields. This allows the user to quickly jump from field to field. By selecting a date in one of the fields, the other field should recognize the information and jump to the same selection.

Do not use the date range selection if:

  • You want to enter a date and a time. In this case, use the date picker or time picker instead.
  • The user’s primary goal is not to select ranges. If this is the case, use the simple date picker.

Responsiveness

The date range selection is fully responsive. It is smaller in compact mode and provides a touch-friendly size in cozy mode. For more information about cozy and compact modes, see the article on content density.

Date range selection (size S)
Date range selection (size S)
Date range selection (size L)
Date range selection (size L)

Components

The date range selection consists of two components: the date range input field (1) and the date range picker (2).

The two clickable areas of the date range selection on all devices
The two clickable areas of the date range selection on all devices

Date Range Input Field

The user can type the date directly into the input field, or use the date picker. You can also show a prompt text in the field (property: placeholder). The system validates the date and gives the user feedback.

1. Current day

2. Currently selected date range

The dates December 19–22 are selected, and December 5 is shown as the current day
The dates December 19–22 are selected, and December 5 is shown as the current day

Date Range Picker

With the date range picker, the user can see a day view, month view, or year view. The current day and the selected date are highlighted. The calendar week is also visible in the day view. The calendar closes when a final day is selected. The user can click the arrows to view the previous and next days, months, or years (depending on the current view).

The selected date is shown with a blue background. The current day is indicated with a purple border in the calendar.

1. Previous month

2. Quick month selection

3. Quick year selection

4. Next month

5. Day selection

Clickable areas of the date range selection
Clickable areas of the date range selection

Optionally, you can offer a footer with OK and Cancel buttons. This gives users an alternative way of confirming the selected date range.

Date range picker with 'OK' and 'Cancel'
Date range picker with 'OK' and 'Cancel'

Behavior and Interaction

Selecting a Date Range

The user can type two dates into the date range input field or click the calendar icon to open the calendar and select a date. These two possibilities work for all devices – desktops, tablets, and smartphones.

Switch View

Clicking an arrow shows the next or previous day, month, or year.

Navigating to the next month
Navigating to the next month

Clicking the month shows an overview of all months.

Opening the month picker
Opening the month picker

If the current month is clicked, the user can change the month. When the user selects a month, the view changes to the day view.

Changing the month navigates back to the date picker. The focus is on the last selected start date.
Changing the month navigates back to the date picker. The focus is on the last selected start date.

By clicking the current year, the view changes to the year view. When the user selects a year, the view changes to the day view.

Opening the year picker
Opening the year picker

Selecting a Range

After the user selects a start date, the dates being hovered over turn light blue to provide visual feedback that a range is being selected. When the user selects an end date, the calendar closes. The range appears in the date input field.

Selecting the start date
Selecting the start date
Selecting the end date
Selecting the end date

Entering Single Dates

The date range selection also allows the user to input single dates. The user can type one date into the input field, or select the same day as a start and end date in the calendar.

Styles

Delimiter

The delimiter visualizes the start and end date. If no delimiter is given, the app uses the one defined for the used locale.

Placeholder

If no range is selected, show a placeholder text to indicate the correct format. If no placeholder is defined, the control shows the default locale placeholder format. You can define your own placeholder, but you must also take localized versions into account.

Date range selection with default placeholder
Date range selection with default placeholder

Validation

Use inline validation to give the user feedback, especially for errors and warnings. Possible validation states are warning, error, success, and information. The date range input field in question is highlighted by a frame in the corresponding color. If the focus is inside the field, an explanation is shown. Ensure that this explanation is as specific as possible.

For more information on how to use the different semantic states, see How to Use Semantic Colors.

Visible frame that shows an error when the field is out of focus
Visible frame that shows an error when the field is out of focus
Error state with meaningful text; the date range input field is focused
Error state with meaningful text; the date range input field is focused
Visible frame that shows a warning when the field is out of focus
Visible frame that shows a warning when the field is out of focus
Warning state with meaningful text; the date range input field is focused
Warning state with meaningful text; the date range input field is focused
Visible frame that shows that additional information is available
Visible frame that shows that additional information is available
Information state with additional information, such as a recommendation
Information state with additional information, such as a recommendation

Guidelines

Display Format

You can choose whether the displayed texts are to be shown in short, medium, or long format, or in another date format like dd–MM–yyyy. However, other date formats (besides short, medium, and long) should be used carefully due to local dependencies.

Long display format
Long display format
Medium display format
Medium display format
Short display format
Short display format

Input Types

The following input types are available. (Note: these examples show German date formats for January 14, 2014.)

  • Unicode CLDR short format: 14.01.14
  • Unicode CLDR medium format: 14.01.2014
  • ISO date format: 2014-01-14
  • ISO date format without delimiters: 20140114
  • Unicode CLDR short format without delimiters: 140114
  • Unicode CLDR medium format: 14012014

Date Formats

Long Date Format

Use the long date format for master list/object list item/title and object header/title. Here are some examples:

  • English (US): January 16, 2022
  • German (DE): 16. Januar 2022
  • Danish (DK): 16. Jan. 2022

Short Date Format

Use the short date format for master list/object list item/list of object attributes if space is a concern. For example, you might need to save space if there is a label with the date. Here are some examples of the short date format:

  • English (US): 1/16/22
  • German (DE): 16.01.22
  • Japanese (JP): 22/01/16

Relative and Medium Date Format

If appropriate, use a relative format for master list/object list item/list of object status. For example: today, 1 day ago, 2 days ago, and so on up to 6 days ago. After 6 days, use an absolute date with the medium format.

Use the absolute date with medium format in the corresponding object header in the details area. Do not use the relative format here.

If screen space is at a premium (for example, if there are too many columns), use the short date format within table cells. Otherwise, use the medium format.

If you need to display the weekday, use the full format. For example:

  • English (US): Sunday, January 16, 2022
  • German (DE): Sonntag, 16. Januar 2022
  • French (FR): dimanche 16 janvier 2022

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Color Palette Popover

The color palette popover encapsulates the color palette and the color picker within a popover. You can use it to offer color selectors on toolbars (for example, triggered by a button). The popover allows users to select one of up to predefined 15 colors, or define any other color in a second step if none of the predefined colors fit.

The color palette popover is also used inside the rich text editor for changing text and background colors.

Color palette popover
Color palette popover

Usage

Use the color palette popover if:

  • Selecting a color from a predefined palette is the typical case.
  • Users may sometimes need to define their own colors, but in most cases a predefined color or default color is sufficient.
  • Selecting a color is needed as a toolbar action. In this case, use a button or menu button to trigger the color palette popover.

Do not use the color palette popover if:

  • You want to let users select a color directly on the page (for example, inside a form). Use the color palette or the color picker instead.
  • Users will nearly always define a color of their own, and rarely use the predefined palette. In this case, use the color picker popover instead.

Responsiveness

The color palette popover supports cozy and compact content densities. On a phone, the color palette popover turns into a full-screen dialog.

Size S
Size S
Size M
Size M
Size L
Size L

Components

The color palette popover consists of:

  • A link to select the default color (optional)
Color palette popover with default color selection
Color palette popover with default color selection
Color palette popover containing only a color palette
Color palette popover containing only a color palette
  • A link that opens a color picker in a dialog (optional). The color picker popover comes in three flavors: simplified, default, and large (property: displayMode). For more information on the three display options, see color picker popover types.
Color palette popover with the option to set any color
Color palette popover with the option to set any color
'More Colors...' opens a color picker dialog
'More Colors...' opens a color picker dialog
You can also display a simplified version of the color picker.
You can also display a simplified version of the color picker.
  • Recent colors (optional). Users can see the last 5 colors they have recently picked. This function helps users to select colors that they have already chosen from the color picker. By default, this feature is visible.
Color palette popover with 5 recent colors
Color palette popover with 5 recent colors
Color palette popover with just one recent color
Color palette popover with just one recent color

Behavior and Interaction

To select a color, users can:

  • Click the Default Color link.
  • Select a color in the predefined color palette or from the recent colors.
  • Click More Colors… to select any other color. This opens the color picker.
  • With the liveChange event, the color change can have an immediate effect and allows app developers to be aware of real-time color changes before they close the popover that contains it.

On a keyboard, users can navigate within the color palette popover using the arrow keys. Pressing SPACE or ENTER selects a color or triggers a link.

As soon as a color has been selected, the color palette popover closes automatically.

Guidelines

  • To trigger the color palette popover, use a button or a value help icon from an input field.
  • Show the selected color in another place (for example, as a color value inside the triggering input field). The color palette popover closes as soon as a color is selected.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Color Palette

You can use the color palette to let users choose a color from a predefined set of colors. The colors are fixed and do not change with the theme.

Color palette
Color palette

Usage

Use the color palette if:

  • The user needs to select one color from a predefined set of colors.
  • The color set contains between 2 and 15 predefined colors.
  • There is no need to offer additional colors.

Do not use the color palette if:

Responsiveness

The color palette supports cozy and compact content densities.

Size S
Size S
Size M
Size M
Size L
Size L

Components

  • A link to select the default color (optional).
  • The color palette, consisting of 2 to 15 color buttons.
  • Recent colors (optional). Users can see the last 5 colors they have recently picked. This function helps users to select colors that they have already chosen from the color picker. By default, this feature is visible.
Color palette with all optional features
Color palette with all optional features
Color palette with 15 colors and just one recent color
Color palette with 15 colors and just one recent color

Behavior and Interaction

Users can select a color with the left mouse button, the tap gesture, or by pressing SPACE or ENTER on a keyboard. The selected color is not indicated in the control itself.

With the liveChange event, the color change can have an immediate effect and allows app developers to be aware of real-time color changes before they close the popover that contains it.

Hovering over a color provides a visual feedback.

To navigate between different colors on a keyboard, use the arrow keys.

Visual feedback on hover
Visual feedback on hover

Guidelines

  • Show the selected color in another place. The color palette does not visualize the selected color.
  • Label the color palette.
  • If you do not want to show the color palette in-place, consider the color palette popover instead.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Rating Indicator

The rating indicator can be used to rate content or to indicate a rating. It enables users to rate an item on a numeric scale. The most popular scale is 1 (lowest) to 5 (highest).

Rating indicator
Rating indicator

Responsiveness

The rating indicator runs on all form factors and therefore works on all devices. It is embedded in a container and thus behaves as part of it.

Rating indicator as part of a form – Size S
Rating indicator as part of a form – Size S
Rating indicator as part of a form – Size M
Rating indicator as part of a form – Size M

Layout

Context

You can use the rating indicator in forms, tables, in a dialog box, or in the filter bar.

Rating indicator as part of a form
Rating indicator as part of a form
Rating indicator in the filter bar / as part of a table
Rating indicator in the filter bar / as part of a table
Rating indicator as part of a dialog
Rating indicator as part of a dialog

Popover with Details

In collaborative rating scenarios, the rating indicator shows an average of all ratings. You may show the sum of ratings in brackets behind the rating indicator as a text or link. You may also add a popover that shows the detailed ratings for the average of all ratings.

Rating details in a popover
Rating details in a popover

Behavior and Interaction

Hover

When the user hovers over the rating indicator, a different icon or image is shown (property: iconHovered). This is an orange star by default.

Select

If enabled for rating, the rating that the user previously selected is shown. When the user performs a rating, an event is triggered.

Types

There are two types of rating indicators:

  • Interactive – used for rating an item
  • Disabled

As the non-interactive state (rating result preview) is not available currently, use the disabled state instead.

Interactive state
Interactive state
Non-interactive state
Non-interactive state
Display mode
Display mode
Disabled
Disabled

Properties

Rating Symbols

You can also specify the URLs for the images or icons that are used as rating symbols (property: iconUnselected). Five star symbols are used by default. Although you can use other images or icons, we generally recommend that you use the star symbol. You can only choose 1 symbol for the unselected and 1 for the hovered state.

Number of Rating Symbols

You can specify the number of rating symbols (property: maxValue). We recommend using a maximum of 7 symbols, although 5 symbols are preferred.

Visual Mode of Rating Symbols

The visual mode defines how float values are visualized: as a half or a full star (property: visualMode). A half star cannot be select by a user. Therefore, it can only be displayed in read-only mode. The main use case for this is to show average ratings.

Size of Rating Symbols

The recommended sizes of the image or icon to be displayed are:

  • Large: 2 rem (32 px)
  • Normal: 1.375 rem (22 px) – default
  • Small: 1 rem (16 px)
  • XS: 0.75rem (12px)
Possible sizes of a rating indicator: L, M, S, and XS
Possible sizes of a rating indicator: L, M, S, and XS

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Calendar Date Interval

The calendar date interval displays a range of days in a single row. The control allows the user to select a single day, multiple days, or a range of days. Content corresponding to the date selection is usually displayed below the control. The user can navigate the date intervals by browsing through them (using the Previous and Next arrows), or by going directly to a specific month or year.

Compared to the regular date range selection control, this control offers a flexible date range and consumes very little vertical space. You can also adapt the width to fit the available horizontal space.

When to Use

  • The user simply needs a calendar. Use the calendar instead.
  • The user wants to pick a single date out of a calendar view. Use the date picker instead.
  • The user wants to pick a date and time. Use the date/time picker instead.
  • The user wants to pick a date range out of a calendar view. Use date range selection instead.
  • The user wants to set a dynamic date, such as “last x months”. Use the dynamic date instead.

Layout

The date interval control is divided into two main areas: date interval navigation, and date interval display and selection.

The navigation area contains two arrows (one to the left, one to the right), which allow the user to navigate easily to the previous and next date ranges. This area also contains month and year indicators, which display the currently selected month and year. These indicators trigger the month and year navigation mode of the control.

The display/selection area is primarily used to display the range of days in the current date interval. You can also display a second row to show the calendar week (property: showWeekNumbers). When the user triggers month or year navigation, a range of months or years is displayed in this section to enable easy interval navigation.

Schematic visualization of calendar date interval
Schematic visualization of calendar date interval

Components

Current Day

The current day is highlighted by a colored frame. Weekends are shaded in a slightly darker gray.

Calendar date interval
Calendar date interval

Special Days

You can mark special days, such as public holidays, with a colored line along the lower edge.

Color markings for special days
Color markings for special days

Behavior and Interaction

The behavior and interaction of the calendar date interval control can be divided into two parts: navigation and selection.

Navigation

Previous/Next

The user clicks the Previous or Next arrow to replace the currently displayed date interval with the previous or next date or period. Previous/Next navigation can be used while the user is in selection mode, as well as in month, year, or year interval navigation mode.

Navigation by Month

The user triggers month navigation mode by clicking the month link above the date range interval. The currently selected month is highlighted. Clicking a month switches the date range interval to the selected month. The user can browse the months by clicking the Previous and Next arrows.

Navigation by month
Navigation by month

Navigation by Year

The user triggers year navigation mode by clicking the year link above the date range interval. The currently selected year is highlighted. Clicking a year switches the date range interval to the selected year. The user can browse the years by clicking the Previous and Next arrows.

Navigation by year
Navigation by year

Navigation by Year Interval

The user triggers the year interval navigation mode by clicking the year interval above the year selection area. The year interval containing the currently selected year is highlighted. Clicking a year interval switches the year range to the selected set of years. The user can browse the year intervals with the Previous and Next arrows.

Navigation by year interval
Navigation by year interval

Selection

The calendar date interval control can be set up for single day selection, multiple day selection, or date range selection.

Single day

The user clicks an unselected day to select that particular day and deselect all previously selected days. Clicking a selected day a second time removes the selection. Only one day can be selected at a time. The selected day is highlighted.

Selection – Single day
Selection – Single day

Multiple days

The user clicks an unselected day to select that particular day. Clicking a selected day a second time removes the selection. Multiple days can be selected. Selected days are highlighted.

Selection – Multiple days
Selection – Multiple days

Date range

The user clicks an unselected day to select the start date. Clicking a second unselected day selects the end date. Both the start and end dates are highlighted. The days in between are highlighted in a lighter color. The minimum range is one day and only one range can be selected at a time.

Selection – Date range
Selection – Date range

Responsiveness

The horizontal space occupied by the control is already minimal, so the responsiveness is limited to the width of the control.

On small screens, the maximum number of days per range interval is automatically reduced to eight.

Cozy
Cozy
Compact
Compact

Examples

Calendar date interval displaying several weeks
Calendar date interval displaying several weeks
Calendar date interval with a selection
Calendar date interval with a selection

Related Links

Elements and Controls

Implementation

 

Color Picker Popover

The color picker popover consists of a color picker within a popover. It enables the user to choose a color from the color spectrum or define it numerically using hex, RGB(A), HSL(A), or HSV(A) values. You can use it to offer color selectors on toolbars (for example, triggered by a button).

Color picker popover
Color picker popover

Usage

Use the color picker popover if:

  • Selecting any color freely is the typical use case (for example, for user-created content).
  • There is no need for or benefit from a predefined color palette.
  • Selecting a color is needed as a toolbar action. In this case, use a button or menu button to trigger the color picker popover.

Do not use the color picker popover if:

  • You want to let users select a color directly on the page (for example, inside a form). Use the color palette instead.
  • A predefined palette is beneficial. Use a color palette popover instead.

Responsiveness

The color picker popover supports cozy and compact content densities. On a phone, the color picker popover turns into a full-screen dialog.

Size S
Size S
Size M
Size M
Size L
Size L

Layout

The color picker popover consists of a popover containing a color picker and a toolbar.

The color picker consists of the following elements:

  • The color picker box for setting lightness and saturation
  • Sliders for setting the hue and transparency (“alpha channel”)
  • Form elements for:
    • Displaying the current and new color settings (Prior to any selection, the default color is white. However, the app developer can set a different predefined color using the setSelected method.)
    • Setting the color as a hexadecimal (hex) value
    • Setting the color as red/green/blue (RGB) value (0 to 255 each)
    • Setting the color as hue/saturation/lightness (HSL) value (hue: 0 to 360 degrees, saturation: 0% to 100%, lightness: 0% to 100%)
    • Setting the transparency (“alpha channel”) value of the color (0.00 for full transparency to 1.00 for opaque)

The toolbar contains two buttons: OK (emphasized) and Cancel.

Types

The color picker popover comes in 3 variants with different levels of complexity:

  • Simplified: The simplified color picker offers basic color manipulation represented only with a hex value, without an alpha value. It shows the current and new color. Text input is only possible for hex values.
'Simplified' color picker popover
'Simplified' color picker popover
  • Default: The default color picker allows all settings. It displays input fields either for red / green / blue / alpha or for hue / saturation / lightness / alpha. End users can switch between both sets of input fields.
'Default' color picker popover
'Default' color picker popover
  • Large: The large color picker allows all settings and displays all fields at the same time.
'Large' color picker popover
'Large' color picker popover

Behavior and Interaction

Colors can be selected using mouse/touch or a keyboard:

  • Mouse/touch: Users select a combination of saturation and lightness in the color picker box (click and drag). Hue and alpha values are selected with sliders.
  • Keyboard: The tab key is used to set the focus on the sliders and input fields. Values are entered using the corresponding input controls. The sliders react on arrow keys, page up / page down keys, as well as on home and end keys. The color picker box is not keyboard-enabled.

The color change can be applied immediately. The OK button confirms the selection of the new color and closes the popover. The Cancel button closes the color picker popover without applying the new color.

Guidelines

  • To trigger the color picker popover, use a button or a value help icon from an input field.
  • Show the selected color in another place (for example, as a color value inside the triggering input field). The color picker popover closes as soon as a color is selected.
  • Use the simplest color picker popover type that does the job.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Select

The select control (also known as a dropdown) is commonly used to enable users to select an item from a predefined list.

Usage

Use the select control if:

  • Users need to select one item exclusively from a short list of options (usually between 2 and 12 items).
  • The values of the option list are of secondary importance and do not need to be displayed right away.

Do not use the select control if:

  • Users need to choose between two options, such as On or Off and Yes or No. In this case, consider using a switch control instead.
  • Users need to pick one item from a very large set of options. In this case, consider using the combo box instead.
  • You need to display more than one attribute. In this case, consider using the input field with a select dialog or a value help dialog instead.
  • The user needs to search on multiple attributes. In this case, consider using the input field with select dialog or value help dialog instead.
  • Your use case requires all available options to be displayed right away, without any user interaction. In this case, consider using radio buttons or a radio button group instead.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

The display of the select control depends on the device:

  • On smartphones, the selection list takes up the whole screen.
  • On desktop and tablet devices, it appears as a popover. If there is not enough space to show the option list below the field, it opens above the field.

Size S

Select option list in full screen - Size S
Select option list in full screen - Size S

Size M

Select option list – Size M
Select option list – Size M

Size L

Select option list – Size L
Select option list – Size L

Size XL

Select option list – Size XL
Select option list – Size XL

Layout

The select control can be placed in toolbars, such as chart toolbarsfooter toolbars, or header toolbars, as well as in forms or tables:

Components

Select Trigger

The trigger to open the option list is either the Select field (1), which also displays the current selection, or an icon (3).

Option List

The option list (2) displays all the items available to the user. The selection is always highlighted. Selecting another option from the list moves the highlight to the selected option.

Full Screen Title Bar for Size S

Opening the select control on a smartphone brings up the option list in full screen mode. The full screen mode can be closed using the icon on the top right corner (5).

You need to set a title for the full screen mode (4). We recommend the following format:

Single selection

Select [Entity]

Example: Select Product

Multi-selection

Select [Entities]

Example: Select Products

 

Anatomy of the select control
Anatomy of the select control
Anatomy of the select control - Size S
Anatomy of the select control - Size S

Behavior and Interaction

Clicking

The Select field always displays the current selection. The user clicks the field to display a list of options to choose from. Once the user selects an option, the list box closes and the selected option is displayed in the field. If there is no Select field but an icon, the user clicks the icon to open the list of options. The currently selected item is always highlighted in the list to help the user identify what has been selected.

Guidelines

Option List

The option list can contain either text-only values or text values with an icon in front. Keep the text values as short as possible.

Only use icons if they help users better identify or understand the options. To set icons, use the icon property for each list entry.

Do not disable values. In most cases, it is completely unclear how to enable them. Hide the values instead.

If you need to indicate that none of the selection options are selected, or you need to allow users to not select an option, offer an appropriate option, such as (Not Selected) or (No Values Selected). Show this option in parentheses and place it at the beginning of the list. For more examples, see the UI text guidelines.

When using the select control to select filter values: If you need to indicate that all items apply, provide All as an option and place it at the beginning of the list.

If your use case requires a blank input field instead of (None), use a combo box instead.

If the select control is placed in a toolbar with an icon as a trigger for sorting, grouping or filtering a set of items, use the texts below for the “not selected” option.

Sort, Group, and Filter:

  • (Not Sorted)
    Note: In most cases, this option is not necessary; just show the default sort settings instead.
  • (Not Filtered)
  • (Not Grouped)

For more information about the toolbar, see the toolbar overview.

Define a default selection whenever possible. If the selected item is not specified, the first one is selected.

Text only
Text only
Icon and text
Icon and text
Selection list with '(Not Selected)' option
Selection list with '(Not Selected)' option

Label

The select control can be displayed with or without a label. If the field is attached to another field, you do not need to define a second label.

Information

Do not provide a blank value to indicate that nothing is selected.

Sorting

The sort option list contains all the items that are available to the user. Choose one of the following styles to order the content:

Logical: Sort items into a meaningful order. Group related options together and show the most common options first, followed by less common options. Sort the options alphabetically if more than eight select options are available. This helps the user find the right option quickly.

Example of logical sorting
Example of logical sorting

Alphabetical: Sort currencies, names, and similar content alphabetically.

Example of alphabetical sorting
Example of alphabetical sorting

Numeric: Sort numeric values into a sequential order, with the lowest number first.

Example of numeric sorting
Example of numeric sorting

Chronological: Sort time-related information into chronological order, with the most recent first.

Example of chronological sorting
Example of chronological sorting

Width

The select control is usually used in forms, where the width is determined by the form element or container in which the select control is embedded.

If you need to restrict the width to a defined value, you can set the width accordingly. However, we do not recommend defining a fixed width. Where possible, use layout containers (such as a form, simple form, or responsive grid layout), and define the width via the layout data property.

Do not allow the control to auto-adjust based on the selection.

Information
If the text length is fixed and doesn’t require localization (for example, currency codes), consider reducing the width.

Width of the Option List

By default, the width of the option list adapts to the width of the longest entry. The maximum width of the option list is set to 600 px.

Maximum width of the option list
Maximum width of the option list

Text Wrap in the Option List

The option list doesn’t support horizontal scrolling. By default, entries that exceed the maximum width of 600 px for the dropdown are truncated. If you expect the dropdown to contain longer entries, we recommend wrapping items in the option list to enable users to read the full text, (property: wrapItemsText). If wrapping is enabled, the text can wrap to multiple lines.

Option list with wrapped text
Option list with wrapped text

Unit of Measurement

You can use the layout options of the form to can add the unit of measurement (UoM) after select. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

Developer Hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

Semantic Colors

Different value states or meanings can be indicated by using semantic colors. The visual states are shown below in their regular state (left) and focused (right). Note that the positive/success state does not show a message on focus.

For more details on the correct usage, see How To Use Semantic Colors.

Neutral
Neutral
Neutral (focus)
Neutral (focus)
Information
Information
Information (focus)
Information (focus)
Success
Success
Success (focus)
Success (focus)
Error
Error
Error (focus)
Error (focus)
Warning
Warning
Warning (focus)
Warning (focus)

Value State Text

The select control can display the value state text even if the dropdown is open. This ensures that the value states are shown in all situations and on all devices. When the user opens the dropdown, the value state sticks to the top and does not scroll away. The control also supports multi-line text for the value state.

Value state text displayed when the dropdown is open
Value state text displayed when the dropdown is open

Read-Only

The select control can be displayed as read-only (property: editable, default = “true”). If the editable property is set to “false”, the value of the select cannot be changed. The control remains focusable, but the background and border are changed to indicate that it is read-only.

Select in read-only state
Select in read-only state

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Text Area

The text area is an input control that allows the user to enter several lines of text.

Usage

Use the text area if you want users to enter multiple lines of text. If you only want them to enter a single line of text, use the text control instead.

Responsiveness

You can set the maximum number of lines to be shown. The amount of text depends on the size of the screen. On smaller screens, the user can scroll down the text area to see the entire text. To indicate that the text continues, the control shows only half of the last line. This also applies for mobile devices.

Components

The text area allows the user to enter multiple lines of text.

Text area – Default
Text area – Default
Text area – Active state
Text area – Active state

You can also set a placeholder (input prompt), which is inherited from sap.m.InputBase; property: placeholder. The prompt text is displayed when the input field is empty.

Text area – With placeholder (input prompt)
Text area – With placeholder (input prompt)
Text area – Selected state
Text area – Selected state
Information
For information on how to manage leading and trailing white space (blanks) when copying and pasting text into input controls, see removing leading and trailing white space.

Behavior and Interaction

Entering and Removing Text

As soon as the user starts typing, the placeholder disappears. It appears again when the user removes all the content from the text area.

You can also limit the number of characters a user can enter. In this case, the text area prevents the user from adding more characters than the maximum value defined (property: maxLength).

Text area – Limited
Text area – Limited

Making Text Non-Editable

You can set the text area to non-editable (property: editable). This mode still allows the user to scroll to the text that is currently hidden.

Text area – Read-only
Text area – Read-only

Disabling Text

You can also set the text area to disabled. In this case, the user cannot edit or scroll (property: enabled).

Text area – Disabled state
Text area – Disabled state

Growing Behavior

The text area control offers a growing property. It gives the control the ability to automatically grow and shrink with its content while the user is typing.

The maximum height of the text area is configurable. Define the height to reflect the space where the control will be located.

Growing text area: The text is aligned to the top of the text area. A new line is added to the bottom of the text area.
Growing text area: The text is aligned to the top of the text area. A new line is added to the bottom of the text area.

Text Area Counter

General Information

If you have set a character limit for the text box (property: maxLength), you can use the text area counter to show a character count (remaining characters, characters over the limit).

To turn on the counter, set the property showExceededText to true. The user can then see all inserted characters, including those that are over the limit.

Basic Interactions

The number of characters allowed is displayed below the text area, aligned to the right. A label indicates how many characters are left.

When the characters are over the limit:

  • Тhe user can continue typing and the text area changes to a warning state.
  • The value of the counter changes.

When the user pastes copied text, characters that are over the limit are selected automatically. The user can delete any excess characters by pressing Delete or Back on the keyboard (or virtual keyboard for phones and tablets).

Text area counter - Default state (within the limit)
Text area counter - Default state (within the limit)
Text area counter components
Text area counter components
Developer Hint
The counter comes with a preset value state for the text area, which controls the appearance of the text area when the text exceeds the character limit. This preset helps the app developer to define the target behavior of the control.

The predefined value state is a warning state.

If the app developer sets additional value states, and the text exceeds the limit, the value states are displayed in the following order (highest to lowest priority):

  • Additional error state available: This results in a higher priority (error + warning = error). If an error state is set, the text area is shown in an error state. When the error is fixed, the text area returns to the warning state until the character count is within the limit.
  • Additional warning state available: An additional warning state has the same priority as the counter warning state (warning + warning = warning). The text area stays in the warning state until all of the issues are fixed. The warning state set by the developer has the higher priority.
  • Additional success state available: In this case, the warning state has higher priority (success + warning = warning). Once the text count is within the limit, the text area shows the success state.

Styles

As with any other input control, you can validate the fields and show the result as a value state of the control (property: valueState). Possible value states are error, warning, success, information, or neutral (none).

For more information, see How To Use Semantic Colors and Form Field Validation.

Text area – Warning state
Text area – Warning state
Text area – Error state
Text area – Error state
Text area - Success state (with thinner border)
Text area - Success state (with thinner border)
Text area - Information state
Text area - Information state

Guidelines

  • As with other input fields, use a label. For exceptions regarding label usage, see the Exceptions section of the Label article.
  • The placeholder does not substitute a label. It can be used to give an additional hint, but should not repeat the label in long format.
  • If you want to use the text area with a fixed text length (property: maxLength), for example, inside a form, use text beside the text area to count down the number of remaining characters while the user is typing.
  • If you are applying the growing behavior of the text area, bear in mind that its maximum height should not exceed the height of the screen.

Saving Forms with a Text Area Counter

If a text exceeds the limit for the text area, there are two options for saving the form:

  • The form can be saved, but only contains the text within the character limit. If you follow this approach, inform the user that only part of the text will be saved. In this case, we strongly recommend setting the text area state to “warning” to indicate that there is a problem with the text.
  • The form cannot be saved until the user edits the text and the character count is within the limit. In this case, we strongly recommend setting the text area state to “error”.

Properties

  • You can provide a width by specifying the average character width (property: cols).
  • You can define the height of the text area by specifying the number of lines of text (property: rows). You can also set the height of the text area (property: height), which overrides the rows property.
  • You can define the type of wrapping for the text area (property: wrapping) as soft, hard, or off.
  • sap.m.TextArea has a growing property that enables the height of the text area to change dynamically while the user is typing.
  • sap.m.TextArea can show a count for the number of permitted characters, and allow users to type/paste text over the limit (property: showExceededText). This property determines whether characters that exceed the character limit are visible.
    • If this property is set to false, the user is not allowed to exceed the number of characters set in the maxLength property.
    • If this property is set to true, characters exceeding the maxLength value are selected on paste, and the counter below the input field displays the number of characters that are over the limit.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Search

A search is a means of accessing information quickly. If an amount of data is too large for users to find something just by scanning through it, you should consider providing a search function.

Search field
Search field

Usage

Use a search field (sap.m.SearchField) if you want to enable users to enter text to search for information. The search field is also the control of choice for filtering down a given amount of information.

Responsiveness

When suggestions are turned on, the suggestion list displays differently depending on the device type.

Size S (Smart Phones)

Clicking the search field opens a new full screen dialog in which items can be selected from a list of suggestions.

Size S
Size S

Size M (Tablets)

Suggestions are shown below the search field.

Size M
Size M

Size L (Desktops)

Suggestions are shown below the search field.

Size L
Size L

Types

SAP Fiori comes with two different search types.

  1. The manual search is triggered explicitly after the user enters text in the search field and clicks the Search button or presses the Enter key.
  2. The live search (also known as “incremental search” or “search-as-you-type”) is triggered by each character that the user enters or deletes. There is a default delay of 400 ms before sending the search data to the back end. This ensures better performance and optimizes user experience. 

Queries that are entered are used to search the back-end data for term matches (not case-sensitive). While a live search uses a “contains” approach, a manual search uses a “starts with” approach. “Contains” means that the result needs to match the query only partly to be a valid result. “Starts with” means that full terms of the result need to start with the entered query to be visualized.

Layout

The search input field (or search box) consists of two parts:

  1. The text input, which is left-aligned. Initially, the field shows a placeholder (Search). As soon as the user enters a character, this prompt text disappears. It appears again if the user deletes the entry.
  2. If a manual search is to be implemented, a search button with a magnifier icon is placed on the right side of this input control. The user clicks this button to trigger the search. In live searches, the magnifier icon is also placed here, but it functions more like an additional indicator to signify that this is a search input field. It also functions as an explicit search button if the user wants to search again for a query that has already been entered.

All item attributes defined by the app development team are searched. When the results are displayed, the items found do not necessarily have to show the attribute through which the item was found. The results are displayed in the same list that contained the original item set. Initial grouping and the order of the list are not affected by the search.

When the flexible column layout is used to show a list-detail relationship, the search field appears at the top of the list. In full screen mode, the search field is placed at the top of the page.

Behavior and Interaction

Entering a Search Term

Search terms can be entered easily into the input field. The search box then displays all full-text search terms. There is no line break and no truncation if the query is longer than the input field. Results might also be displayed that do not match the query in their title or subtitle. This might be because details can also be searched for. The user can see the matching terms in the specific details section.

Deleting a Search Term

The user can click the “X” icon  ) button to remove the text from the field. In the case of the live search, this also resets the search. In a manual search, deleting the search term and then triggering the search resets the search results.

Refreshing

If the Refresh button is available, the user can update the list without triggering a new search. This is usually needed when backend data changes quickly and often.

If the currently selected item is no longer available after the list has been refreshed, the next item in the line is selected. If no next item is available, the first item in the line should be selected next.

Search field with 'Refresh' button
Search field with 'Refresh' button

On mobile phones and tablets, the Refresh icon is not visible in the search field. In this case, Pull Down to Refresh is used instead. The Pull Down to Refresh arrow icon is animated and spins to signal that the user should release it.

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?fnFunctionoListener?) Attach event handler fnFunction to the liveChange event of this sap.m.SearchField.
  • detachLiveChange(fnFunctionoListener) 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?fnFunctionoListener?) Attach event handler fnFunction to the search event of this sap.m.SearchField.
  • detachSearch(fnFunctionoListener) Detach event handler fnFunction from the search event of this sap.m.SearchField.
  • fireSearch(mArguments?) Fire search event to attached listeners.

If a Refresh button is needed:

To show the Search button:

To ensure the focus is set to input:

If the search is triggered automatically when the value of the field is changed (unlike the liveChange event, the change event is not fired for each key press):

  • attachChange(oData?fnFunctionoListener?) Attach event handler fnFunction to the change event of this sap.m.SearchField.
  • detachChange(fnFunctionoListener) Detach event handler fnFunction from the change event of this sap.m.SearchField.
  • fireChange(mArguments?) Fire change event to attached listeners.

Guidelines

  • Implement the live search whenever possible.
  • Use a manual search only if the amount of data is too large and if your app would otherwise run into performance issues.
  • Show an appropriate prompt text:Search if queries are sent to all connected services, or Search In: if the search is limited to a certain source or providing service.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Table Personalization Dialog

The table personalization dialog allows you to display and modify table settings. It is a UI pattern that defines the column order and visibility.

Usage

Use the table personalization dialog if:

  • You have small tables.
  • You have a manageable number of columns.

Do not use the table personalization dialog if:

  • You have large tables.
  • You have a lot of columns to manage.

For larger tables you can use the P13n dialog (sap.m.P13nDialog) instead.

Responsiveness

On a desktop and tablet, the control appears as a dialog window.

On smartphone devices, always display the table personalization dialog in full screen mode.

Smartphone - Size S
Smartphone - Size S
Tablet - Size M
Tablet - Size M
Desktop - Size L/XL
Desktop - Size L/XL

Layout

Position on the Screen

The dialog always opens in a modal window in the center of the screen.

For smartphones, stretch the dialog to fill the entire screen. For tablet and desktop devices, keep the modal window.

Layout of the Dialog

The table personalization dialog comprises the following five areas:

(1) Header

(2) Toolbar

(3) List Header

(4) Column list

(5) Footer toolbar

Table personalization dialog – Overview
Table personalization dialog – Overview

Components

The table personalization dialog contains the following sections:

Dialog Header

The header displays the dialog title and the Reset button to revert to the initial state.

Dialog header
Dialog header

Toolbar

The toolbar displays the Move Column Up and Move Column Down buttons, and the Search field.

Toolbar
Toolbar

List Header

The list header displays the Select All checkbox for selecting all columns.

List header
List header

Column list

The column list displays the available columns. The user can filter the selection using the search field in the toolbar.

Column list
Column list

Footer toolbar

The footer toolbar displays an OK and a Cancel button.

Footer toolbar
Footer toolbar

Behavior and Interaction

The table personalization dialog is resizable.

Open the Dialog

To open the table personalization dialog, the user clicks the  (Settings) button on the right-hand side of the table toolbar.

Table with settings button
Table with settings button
Table personalization dialog opened
Table personalization dialog opened

Show or Hide Columns

To show or hide columns, the user selects or deselects the checkbox for a column (list item).

The column is hidden in the table
The column is hidden in the table
The column is visible in the table
The column is visible in the table

The user can also show or hide all columns with just one click. A checkbox on the left-hand side of the list header enables all list items to be selected or deselected.

Show all
Show all
Hide all
Hide all

Move Columns

Users can change the order of the columns in the table using the   (Move Column Up) and   (Move Column Down) buttons in the toolbar.

To change the order, click an item (not on the check box, but on the rest of the line), and click the button: Items on top are farthest to the left in the table, items on bottom are farthest to the right.

Move buttons
Move buttons
The column 'Supplier' will be moved. It is not checked, though, therefore the result of moving this column will not be visible in the table.
The column 'Supplier' will be moved. It is not checked, though, therefore the result of moving this column will not be visible in the table.

Search/Filter Columns

Users can search for or filter columns using the search field in the toolbar.

Search field
Search field

The search is a live search (also known as “search-as-you-type”), which is triggered by each character the user enters or deletes. For more information, see search.

To clear the filters, the user can delete all characters manually, or use the  icon.

The list then shows all columns again.

Search while you type
Search while you type

Reset Personalization

The Reset button in the dialog header resets all settings to the initial state.

If the table personalization dialog is used together with variant management, the button resets the changes to the initial state of the selected variant.

Reset button
Reset button

Confirm/Cancel Changes

The changes are applied when the user closes the dialog with the OK button.

The Cancel button closes the dialog without applying the changes.

OK and Cancel buttons
OK and Cancel buttons

Resources

Elements and Controls

Implementation

Feed and Notes

Feeds and notes are commonplace in many SAP Fiori applications. The sap.m.FeedInput control allows users to input and post plain text, while the sap.m.FeedListItem control handles and displays this text. Both can be used individually, but they also complement each other well to create a simple feed or notes control.

Usage

Feed Input

Use the feed input if:

  • A user needs to input small amounts of text without formatting.
  • You expect multiple instances, such as notes or feed entries.

Do not use the feed input if:

  • The user needs to format the text (rich text editor).
  • You need only a single text box instance. In this case, use the text area (for multiple lines) or the text control (for a single line).

Combination of Both Controls (as Feed or Notes Control)

Use both controls if:

  • You need a feed to show textual posts.
  • Your users need to input notes.

Do not use both controls if:

  • You expect extensive social interaction in the feed.
  • Users need to reply at item level instead of creating a new post.
  • You want to display SAP Jam feeds.

In these cases, use the social timeline instead (requires SAP Jam).

Responsiveness

Due to their responsive behavior, both controls can be used in small and large view ports or screens.

For better usability, we highly recommend that you do not stretch the controls across the full width on large screens – 2/3 or even 1/2 works just fine. This can easily be achieved using the grid layout .

Feed – Size S
Feed – Size S
Feed – Size M
Feed – Size M
Feed – Size L
Feed – Size L

When the width of the available space falls below 25 rem (for example, in portrait mode on smartphones), the two controls respond as follows:

  • If a user image previously appeared in the feed input, it will be omitted in narrow screens to give the text field more space.
  • If there is no user image, there will be no visual change.
Feed input – Responsiveness
Feed input – Responsiveness

In the feed list item, the user’s name, image, and the time stamp move on top of the text. If there is no image, the name and time stamp are left-aligned together with the text.

Feed list item – Responsiveness – With image
Feed list item – Responsiveness – With image
Feed list item – Responsiveness – Without image
Feed list item – Responsiveness – Without image

Layout

Feed Input

The feed input consists of:

  • A text input field with a placeholder (input prompt)
    Example: Add a comment
  • A Send button
  • An optional user image

You can also choose not to show user images at all. In this case, the size of the input area increases automatically.

Feed input – Layout – With user image
Feed input – Layout – With user image
Feed input – Layout – With generic user image
Feed input – Layout – With generic user image
Feed input – Layout – Without user image
Feed input – Layout – Without user image

Feed List Item

The feed list item consists of the user’s name and an optional picture of the user who wrote the note or update. The name can contain a link that triggers a quick overview of the user’s profile data. The actual text written by the user follows the name. Below it is a separate byline that can contain a time stamp and an attribute in the form of free text. This allows you to put in your own attribute, such as Approval, Internal, or External. Both the time stamp and the attribute are optional.

If the name is a link, the picture should also be linked with the same attributes.

Feed list item – With user image and linked name
Feed list item – With user image and linked name

If the user does not have a picture assigned, a placeholder is shown instead:

Feed list item – With generic user image and linked name
Feed list item – With generic user image and linked name

The name (and picture) can also be read-only, that is, without a link:

Feed list item – With user image but without links
Feed list item – With user image but without links

If the app does not support user images, they can be omitted:

Feed list item – Without user image but with linked name
Feed list item – Without user image but with linked name

Here, too, the name can be read-only:

Feed list item – Without user image and read-only name
Feed list item – Without user image and read-only name

It’s also possible to display rich text (formatted text) in the feed list item. This feature should be handled with care as it allows for countless custom layouts.

Please see that you use it responsibly and provide your users with a consistent experience. Only deviate from the default layout and font if absolutely required by the use case.

Example use case: Render URLs as links.

Feed list item – Layout – Rich text
Feed list item – Layout – Rich text
Information
The items in the feed list must be homogeneous. This means that they must contain the same layout and visualization. For example, it is not possible to have a feed containing both linked and plain names, or both user images and default images.

Special Case: Multiple Types of Notes

Apps sometimes need to discern between different types of notes. There is an easy way to allow users to choose which type they want to see or add to the list.

You can place a toolbar containing a select control at the top of the feed input control. From there, users can select the type of notes, such as Internal Notes or External Notes. The list of notes must contain only the type selected. If the user adds a note via the feed input, the type must be set automatically according to the selection.

Interaction – Note Types

Components

The feed input and feed list item do not contain subcontrols. However, you can easily combine them to create a simple feed or notes control.

Although the feed input counts as a single control, the input area inherits its behavior from the sap.m.TextArea control.

Behavior and Interaction

Send Message

Initially, the feeder contains a placeholder (input prompt), and the Send button is disabled, with reduced opacity.

Clicking into the input field puts the focus on the field and allows to start typing.

When the user starts to type, the placeholder disappears and the Send button becomes active and more prominent.

If the available width is below 25 rem (for example, in portrait mode on a smartphone), the picture is removed.

To send the text, the user must explicitly click the Send button. Pressing Enter on the keyboard (on-screen or physical) results in a line break.

Feed input – Behavior
Feed input – Behavior

Show More Text

When the text exceeds a certain number of characters (you can overwrite the default value), the rest of the text is truncated and a MORE link appears after the truncated section.

The MORE link indicates the possibility of expanding the section of the feed list item itself. Hovering over the link underlines it.

Show Less Text

When the user expands the text, the name of this link changes to LESS,  but still behaves the same way as before.

Modify “MORE” / “LESS” links to “More / Less” to be consistent with other components.

More link
More link

Feed and Notes in Tables

In tables, users sometimes need to see if an object has a comment (or feed or note) without further navigation, and even be able to add/edit right from the table.

Add an additional column, named according to the type of user input, such as Comment, Note, or Feed.

Place a link inside each cell with the appropriate action (row: Comment, link: Comment / row: Feed, link: Post).
If there can be more than one item, add a counter after the text as well (see example on the right).

This solution works with every table control.

Feed and notes in tables (1)
Feed and notes in tables (1)

Optional:
Depending on the use case, it might help users if they can see the latest note. The responsive table allows the feed list item (sap.m.FeedListItem) to be used inside a cell.

Reduce the property “maxCharacters” to an amount that your table can handle.
Note that once the maximum number of characters has been reached, a MORE link allows users to expand the text. Technically, this is no problem for the responsive table, but you need to ensure that the layout of your page allows this kind of expansion.

Place a link below the feed list item to allow users to add something (as described above).

Feed and notes in tables (2)
Feed and notes in tables (2)

When the user clicks a link, such as Comment or Note, display a dialog showing all comments (notes, feed entries, and so on) along with possible actions, such as Add or Edit, depending on your use case.

There are several ways to show notes (comments, feed entries, and so on) in a dialog:

  • You can use the feed list item (and feed input) as described in this article.
  • If only one single note is allowed, you can use the text area.
  • For a large feed, you can use the timeline control (SAP Jam is required for social features).

Actions On Feed List Items

Applications can define actions that users can perform on individual feed posts. The two most typical actions are Edit and Delete. Other actions can be introduced as required by the use case. To keep the feed as lightweight as possible, don’t overwhelm users with too many actions or complicated actions (max. 5 per post).

Interaction - Actions
Interaction - Actions

Styles

By default, feed entries are separated by divider lines. We recommend that these separators remain enabled, since they help distinguish between individual posts. However, if your list is expected to hold only a handful of entries, you can disable the separators by setting the showSeparators property at list level (not at list item level) to none.

Guidelines

Because the feed list item is built on the basis of the standard list item, it inherits multiple properties that may not make sense in a feed use case.

Use only properties that are described in this article. Especially making the entire feed list item clickable can lead to functional issues and usability problems.

Don’t stretch the feed input or the feed list items across large screens (size L and beyond). This will have a negative effect on usability and readability. Instead, only use 1/3 or even 1/2 of the screen. Implement this with the grid layout .

If you display formatted text (rich text) in the feed list item, use formatting that is beneficial to users, not decorative formatting. Use formatting responsibly, and provide your users with a consistent experience. Deviate from the default layout and font only if absolutely required by the use case (example: render URLs as links).

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

  • No links.

Implementation

P13n Dialog

Intro

The p13n dialog control provides a dialog for tables that allows the user to personalize one or more of the following attributes:

  • Columns (visibility and order of columns)
  • Sort (sorting of table values)
  • Filter (filtering of table values)
  • Group (grouping for specific attributes)

These tabs can be shown in any combination, as the use case requires.

The P13n dialog is intended for complex tables with a large number of columns and the need for complex queries for sorting, grouping, and filtering.
For simple tables, see view settings dialog and table personalization dialog.

The P13n dialog can be triggered in the table toolbar using the corresponding buttons in the top right-hand corner of the table.

The dialog is shown centered, either as a dialog (on desktop and tablet devices) or as a full-screen dialog (on mobile devices).

Dialog buttons within the table toolbar
Dialog buttons within the table toolbar

Usage

Use the P13n dialog if:

  • The user is able to personalize more than 20 or so columns.
  • You need several functions for sorting, grouping, and so on.
  • You are using the analytical table.
  • Complex queries have to be built for the relevant table.

Do not use the P13n dialog if:

  • The user is able to personalize fewer than about 20 columns.
  • You only need a simple column show/hide feature.

Responsiveness

The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), the dialog is shown as a dialog. For size S (smartphones), the P13n dialog is displayed as a full-screen dialog.

Size S – Columns
Size S – Columns
Size M
Size M
Size L
Size L

Components

The P13n dialog consists of four different tabs that can be used separately or combined, as required by the use case:

  • Sort
  • Filter
  • Group
  • Columns

App developers can add more tabs manually.

Behavior and Interaction

Columns

The Columns tab allows the user to change the table columns that are shown and the order in which they are displayed.

The list contains all of the table’s possible columns in the form of list items with checkboxes. The checkboxes of the currently displayed columns are selected.

Another button next to the search field in the table toolbar allows the user to toggle between showing all columns and only those that are currently selected in the list.

Show/Hide

To show or hide a column, select or deselect the appropriate checkbox.

Reorder

To change the order of the columns, simply mark one list item and use the buttons on the right-hand side of the table toolbar to move them up or down. The order of the columns from top to bottom corresponds to the order on the table from left to right.

Search

If the table has numerous columns, the user can use the search field in the table toolbar to find a specific column more quickly. As soon as the user enters the first letter, the resulting columns are displayed instantly.

Column settings in the P13n dialog
Column settings in the P13n dialog

Sort

The Sort tab allows the user to sort the table content according to the chosen attributes, and also in either ascending or descending order.

The sort criterion consists of two input fields. In the first field, the user can choose a column by which the table is to be sorted. In the second field, the user chooses the sort order (ascending or descending).

For more complex sorting needs, the user can add the required number of criteria by clicking the plus “ ” sign at the end of the line.

The order of the criteria is exactly the same as the order in which sorting is applied to the table.

Sort settings in the P13n dialog
Sort settings in the P13n dialog
Information
Using the sort feature on column headers replaces ALL sort options in the dialog!

Filter

The Filter tab allows the user to filter the table information according to specific criteria.

Users can add filters with the Add button or remove them by clicking the  (Remove Filter) icon at the end of each filter item.

Column

In the first input field, the user selects the column to be filtered. Any column can be selected, including columns that are not currently visible.

Operator

The second field contains the operator that is applied to the filter value (such as greater than or not before).

To include or exclude filter criteria, users select the relevant operator from the Include or Exclude section of the dropdown list. For example, equal to to include a value, and not equal to to exclude it.

If individual filter criteria have Boolean values, the operator is always “equal to” and the operator dropdown is disabled.

Available operators:

String (Text)

  • between
  • contains
  • equal to
  • begins with
  • ends with
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Number

  • between
  • equal to
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Date

  • between
  • equal to
  • after
  • on or after
  • before
  • before or on

Boolean (true/false)

  • equal to

Value

The last field contains the value by which the selected column is filtered. The kind of input field that is provided depends on the data type of the selected column and the selected operator. For example, the value field for fixed or boolean values could be a dropdown list, and input field with suggestions, or a date picker. Two or even more fields can be provided, as required by the use case.

Information
If there is a filter bar, use the filter bar functionality and deactivate the filter feature of the P13n dialog.

Group

The Group tab enables the user to group the table data by one or more columns.

In the first selection field, all columns are provided for selection. The user can select a checkbox on the right of the column selection field if the selected field is to be displayed as a column anyway.

For more complex grouping scenarios, the user can add more grouping options by clicking the plus “ ” button on the right-hand side of each grouping line. This option only works with the analytical table.

The grouped table shows the selected field as the group header, which can be expanded or collapsed.

Under the group headers, all subgroup headers and all applicable table entries are displayed.

Group tab in the P13n dialog
Group tab in the P13n dialog
Information
To group by a specific column, that particular column must be marked as visible on the Columns tab!

Guidelines

For opening the dialog from a table toolbar, use different buttons for each function (sort, filter, group, column settings). With each button, open the P13n dialog with just the corresponding tab. Do not display the other tabs.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Value Help Dialog

Intro

The value help dialog is a UI pattern that helps the user find and select single and multiple values. The user can also define and select multiple conditions. The value help dialog is generally called from an input field or a multi-input field by clicking the selection icon (value help icon) of the input field.

Usage

Use the value help dialog if:

  • The user is searching within a dataset that contains more than 1,000 items.
  • The user needs to use different attributes to find an object (such as city, company name, and so on).
  • The user needs to define conditions, such as ranges and exclusions.

Do not use the value help dialog if:

  • There is a simpler control that fits the use case. Always start with the least complex control. For example, use the select control if the user needs to select only one item from a short list.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

The behavior of the value help dialog on a phone differs from its behavior on a tablet or desktop device. Both the navigation and the positioning of the selection area differ depending on the device.

Value help dialog - Size S
Value help dialog - Size S
Value help dialog - Size M
Value help dialog - Size M
Value help dialog - Size L
Value help dialog - Size L

Components

The value help dialog contains the following components:

1) Header
2) Icon tab bar / list control (phone)
3) Search template (optional)
4) Basic search
5) Go button
6) Filters
7) Result list
8) Selected items and conditions
9) Footer toolbar
10) Area for defining conditions, such as ranges and exclusions

Header (1)

The header bar contains the dialog title. See the Guidelines section below.

Icon Tab Bar / List Control (Phone) (2)

Depending on the device, the following controls are used to display the content of the value help dialog:

  • Smartphones: The start dialog provides a list (sap.m.List) with the standard list items (sap.m.StandardListItem), Search and Select, and Define Conditions to navigate between the different dialogs.
  • Tablet and desktop devices: The value help dialog contains an icon tab bar (sap.m.IconTabBar) to navigate between the Search and Select and the Define Conditions tab.
  • Both controls have a counter in the title that indicates the number of items/conditions selected.

Search Template (3)

Search templates allow the user to display different or additional fields in the filter area and result list. Depending on the use case, the user can switch between the different search templates in order to use different fields when searching. For example, the search template “Customer (by Company Code)” displays the additional field “Company Code” in the filter area and result list.

Basic Search (4)

The basic search finds all results that are somehow related to the input. For example, the search term “A” returns all the results containing the letter “A”.

Always offer the basic search in the value help dialog. Position the basic search to the right of the search template control. If there is no search template control, left-align the basic search.

Go Button (5)

The Go button triggers the search and filters the result list.

Filters (6)

The filter area offers a filter field for each column in the result list. In some cases, there can be specific filter fields that do not have a corresponding column on the UI. These fields typically come from the back-end service.

Value help dialog - Filters
Value help dialog - Filters

For the basic search with filters, the filter bar (sap.ui.comp.filterbar.FilterBar) is implemented in advanced mode. Advanced mode differs from basic mode in the following ways:

  • There is no Filters link or a dialog to make additional filter fields visible. All filter fields fields are added automatically to the filter area.
  • There is a toggle button to show and hide the filters.
  • In each of the filter fields, users can use operators like “between” or “lower than” to define conditions.

Always hide the filter area in the value help dialog by default. Only show the filter area by default if the basic search can’t be provided.

Note that the value help icon of the Product ID field in the current value help dialog will open only the Define Conditions screen. The full value help dialog is not shown in order to prevent endless loops. For example, the value help icon of the Product Name or Category field in the value help for a Product field will navigate directly to the Define Conditions: Product screen.

Using the Filters

Users can enter operators (such as “=“) to define the conditions directly within the field without opening the Define Conditions tab.

Users must use the following notation to get results:

Operator Input Notation Example
between valuevalue 000100
equal to =value =0001
contains *value* *1*
starts with value* 001*
ends with *value *5
less than <value <100
less than or equal to <=value <=200
greater than >value >0300
greater than or equal to >=value >=0500
not between !(valuevalue) !(000100)
not equal to !(=value)  !(=0)
does not contain !(*value*)  !(*1*)
does not start with !(value*)  !(001*)
does not end with !(*value)  !(*5)
not less than !(<value) !(<100)
not less than or equal to !(<=value) !(<=200)
not greater than !(>value)  !(>0300)
not greater than or equal to !(>=value)  !(>=0500)
empty <empty>   <empty>
not empty !(<empty>)    !(<empty>)
Using an operator to filter the result list
Using an operator to filter the result list

Result List (7)

  • The result list is populated on initial load by default.
  • If you transferred values from the input field to the basic search field of the value help dialog, the results are filtered accordingly. Only the entered (or modified) value is transferred to the basic search. Type-ahead suggestions are ignored. The search is triggered automatically when the dialog opens.
  • If available, display the ID and description of the business object in the first and second columns. Display additional information in the next columns.
  • We recommend a maximum of five columns in the result list.

Selected Items and Conditions (8)

The selected items and conditions are displayed in a tokenizer (see token for more information). Each selected item or condition is displayed as one token.

There is no longer a visual difference between included and excluded items and conditions. They are now differentiated using operators (see Using the filters).

Footer Toolbar (9)

The footer bar offers the OK and Cancel buttons.

Area for Defining Conditions (10)

In the Define Conditions tab, you can use the following operators to define single and multiple conditions:

  • between
  • equal to
  • contains
  • starts with
  • ends with
  • less than
  • less than or equal to
  • greater than
  • greater than or equal to
  • empty
  • not between
  • not equal to
  • does not contains
  • does not start with
  • does not end with
  • not less than
  • not less than or equal to
  • not greater than
  • not greater than or equal to
  • not empty

For convenience, the operators are grouped into two categories: Include and Exclude.

Each condition is displayed as a token in the Selected Items and Conditions tokenizer.

Information
The operator dropdown list may not contain all the operators listed above. The type of field value determines which operators are available.
Developer Hint
For information on how to manage white space characters (blanks) when users copy and paste text into input controls, see Removing Leading and Trailing White Space.
Define Conditions - Operators List
Define Conditions - Operators List

Behavior and Interaction

Basic Search and Filters

  • The basic search (mandatory) and filters (optional) are triggered by clicking the Go button. The search results are shown in the result list.
  • If data was already entered in input field from which the user triggered the value help, this data is transferred to the basic search and the results are then filtered accordingly.
  • The basic search performs a search across all fields that are displayed in the filter area and the result list.

Selecting Items and Defining Conditions

Depending on your use case, the value help dialog can offer different selection options:

  • Select a single item
  • Define a single condition
  • Select multiple items
  • Define multiple conditions
  • Select multiple items and define multiple conditions

Users open the value help dialog by clicking the value help icon in the input field. The next steps depend on the use case and form factor (smartphone or desktop/tablet).

The different use cases are described in the sections below.

Select a Single Item (Smartphone)

Tapping the value help icon opens the dialog. As soon as an item is selected, the value help dialog closes automatically.

Single item selection on a smartphone
Single item selection on a smartphone

Select a Single Item (Desktop/Tablet)

Clicking the value help icon opens the value help dialog for single selection. The icon tab bar and the Selected Items and Conditions are hidden. As soon as an item is selected, the value help dialog closes automatically.

Single item selection on a desktop/tablet device
Single item selection on a desktop/tablet device

Define a Single Condition (Smartphone)

Tapping the value help icon opens the Define Condition tab. Users define a condition by choosing the relevant operator and entering the value or values in the corresponding input field(s).

In this example, we have defined a range.

Defining a single condition on a smartphone
Defining a single condition on a smartphone

Define a Single Condition (Desktop/Tablet)

Clicking the value help icon opens the Define Condition tab. Users define a condition by choosing the relevant operator and entering the value or values in the corresponding input field(s).

In this example, we have defined a range.

Defining a single condition (desktop/tablet)
Defining a single condition (desktop/tablet)

Select Multiple Items and Define Multiple Conditions (Smartphone)

Tapping the value help icon displays the start dialog.

  • The Search and Select tab is used to select multiple items.
  • The Define Conditions tab is used to define multiple conditions.
  • The counters in the titles of both tabs represent the number of selected items/defined conditions.

All selected items and conditions are added as tokens to the Selected (n) field at the bottom of the start dialog. The counter n indicates the combined number of items selected and conditions defined.

Start dialog
Start dialog
Selecting multiple items on a smartphone
Selecting multiple items on a smartphone
Defining multiple conditions (smartphone)
Defining multiple conditions (smartphone)
Filters on a smartphone
Filters on a smartphone

Select Multiple Items and Define Multiple Conditions (Desktop/Tablet)

Clicking the value help icon displays the icon tab bar with the Search and Select and Define Conditions tabs.

  • The Search and Select tab is used to select multiple items
  • The Define Conditions tab is used to define multiple conditions.

All selected items and conditions are added as tokens to the Selected Items and Conditions (n) field at the bottom of the dialog. The counter n indicates the combined number of items selected and conditions defined.

Selecting multiple items and conditions on a desktop
Selecting multiple items and conditions on a desktop
Selecting multiple items and conditions on a desktop
Selecting multiple items and conditions on a desktop

Define Multiple Conditions (Smartphone)

Tapping the value help icon opens the start dialog with the Define Conditions tab.

The selected values are added as tokens to the Selected Conditions at the bottom of the start dialog.

Start dialog
Start dialog
Defining multiple conditions on a smartphone
Defining multiple conditions on a smartphone

Define Multiple Conditions (Desktop/Tablet)

Clicking the value help icon opens the Define Conditions tab.

The selected values are added as tokens to the Selected Conditions at the bottom of the start dialog.

Defining multiple conditions on a desktop
Defining multiple conditions on a desktop

Copying and Pasting Multiple Values

The area for defining conditions allows the user to enter multiple values at once (copied from the clipboard).

Users can paste more than one value into the value input field. In this case, the condition row repeats with the previously selected condition and shows one value per row.

If there are more than 10 rows of conditions, pagination is added to top of the respective area.

Copying and pasting multiple values
Copying and pasting multiple values

Guidelines

Dialog Title

The dialog title differs depending on the device and whether multiple or single selection is used.

For smartphones:

  • Start dialog: [Object] (for example, Company)
  • Search and Select Dialog: Search and Select
  • Filters dialog: Show Filters
  • Define single condition: Define Condition
  • Define multiple conditions: Define Conditions

For tablet and desktop devices:

  • Selection of multiple items combined with selection of multiple conditions: [Object] (for example, Company)
  • Single item selection: Select: [Object] (for example, Select: Company)
  • Define single condition: Define Condition: [Object] (for example, Define Condition: Company)
  • Define multiple conditions: Define Conditions: [Object] (for example, Define Conditions: Company)

Filtering

If necessary, also provide value help for fields offered in the filters. However, do not provide the full value help dialog for the ID and description fields of the business object that is being selected. For these two fields, make sure that the value help icon opens only the Define Conditions screen.

For example, in a value help dialog for selecting the customer, do not offer full value help for the Customer ID and Customer Name fields. Instead, try to use the value help in combination with a helpful suggestion.

Constant Parameters

You can use constant parameters to pre-filter suggestion lists, drop-downs, and the value help results list. Users can’t change these parameters.

Do not show parameters with constant values as filterable fields in the filter bar of the value help dialog or in the result table columns. Constant values should not be visible to users in any way.

Related Links

Elements and Controls

Implementation

Planning Calendar

The planning calendar allows users to see different appointments at the same time and to create new appointments. It allows the user to display appointments for several objects, such as a team calendar, and compare them to each other.

Usage

Use the planning calendar if:

  • You want to compare objects of the same type with each other over a period of time.
  • You require responsive behavior.
  • You have less than 100 lines in the calendar.

Do not use the planning calendar if:

  • You want to show a calendar for one object and a detailed overview of appointments over a long time interval.
  • You want to show a complex or graphical representation. In this case, please use the Gantt chart.
  • You have more than 100 lines in the calendar. In this case, please use the Gantt chart.

Responsiveness

In size S, the control provides pop-in behavior, which allows the user to see as many appointments as possible and to connect them with the corresponding object. If the toolbar contains too many actions for the space available, the overflow icon appears.

The interval section displaying the hours, days, and months is responsive and shows 12 values in size L, 8 values in size M, and 6 values in size S. You can override this behavior, but you should then check that the responsiveness is still working.

Planning calendar - Size L
Planning calendar - Size L
Planning calendar - Size M
Planning calendar - Size M
Planning calendar - Size S
Planning calendar - Size S

Types

You can define what size of interval the calendar should show, and whether multi selection should be possible. Additionally, the row header and the interval appointments are optional.

The control allows multi-select mode to be shown for the list items. This can be used, for example, to delete multiple objects from the view.

An app development team must decide whether to show the planning calendar with or without multi-select mode, or whether users should be able to switch between the two modes. Hiding the interval appointments of every object is optional.

The planning calendar can also be used without a row header. In this case, the row header disappears and only the appointments are visible. It can be used to show the calendar of one object. Note that the control was built mainly to compare time slots of different objects. For this reason, the time axis is shown horizontally and, depending on the interval, the appointments might shrink to smaller size. In this case, the text is cut off rather than truncated.

Components

This section describes the various components of the planning calendar.

Parts of the planning calendar
Parts of the planning calendar

The control consists of different parts:

  1. Header
  2. Toolbar
  3. View switch
  4. Navigation
  5. Time strip for hours/days/months
  6. Row header
  7. Row
  8. List item
  9. Interval appointment
  10. Appointment

1. Header

The header contains the toolbar and the navigation.

2. Toolbar

The toolbar consists of the calendar title (optional) and the toolbar actions, including a default view switch. You can add generic and app-specific actions that are relevant for your use case (such as creating an appointment, search, settings, showing the calendar legend, and so on). Always place actions that affect the entire calendar in the toolbar.

For more information, check out the toolbar guideline article.

The generic actions are as follows:

Search
Create Appointment
Add New Contact (icon: add-contact)
Multi-Select Mode (icon: multi-select)
Legend (icon: legend)
Settings (icon: action-settings)
Full Screen (icon: full-screen/exit-full-screen)

3. View switch

The view switch allows the user to switch between different time intervals (calendar views). Depending on the number of available calendar views, the view switch can be a segmented button (four views or less) or a select control (five views or more).

The 1 Month view shows an entire month. On desktop devices, the 1 Month view always displays an interval of 31 days. When the displayed month is shorter (28, 29, 30 days), days from the following month are displayed. They have a different visual state and serve as navigation to the following month.

The 1 Month view has an additional style for half-column appointment distribution, which is mainly used to avoid overlapping. The property appointmentRoundWidth can be set to “HalfColumn” or “None” (default). Currently, the width of the appointment is always rounded to 12 hours.
Note: This property is also applied when the calendar interval type is Days and the view shows more than 20 days.

On size M and Size S, the 1 Month view is adaptive. It consists of a calendar and a list of appointments for the selected day.

If you offer the 1 Week view, we strongly recommend displaying a different number of days in the Days view (more or less than seven). Otherwise, the user might be confused, as navigation for the two views differs.

The default calendar views are Hours, Days, Months, 1 Week, and 1 Month. The app developer can choose which views to include, depending on the use case, and how many values are shown for each view. App developers can change the default number of values shown, but they should then ensure that the app is still responsive. The app developer can also create custom views.

4. Navigation

The navigation area contains back and forward arrows, the Today button, a date interval link, and the time strip. Clicking the Today button takes the user to the period containing the current day. Clicking the date opens a date picker for direct navigation.

5. Time strip for hours/days/months

The time strip reflects the selected view, and shows the hours, days or months that are currently visible. In all views that show days (Days, 1 Week, 1 Month), you can display calendar weeks in an additional line below the time strip (property: showWeekNumbers).

6. Row header

The row header identifies the object for which the appointments are shown. It pops in if there is not enough space. The row header can contain a picture or icon, a title, and a subtitle.

You can also add an action on the row header (event: rowHeaderClick).

7. Row

The row contains all appointments for an object. You can turn the alternating row coloring on or off. By default, the alternating rows option is turned on.

8. List item

The list item contains the row header, row, appointments, and interval appointments. Each row can show different working and non-working days.

If the users have a specific working schedule, the non-working days can be different on each row. This can be applied not only for weekends, but also for non-working days based on specific schedule differences.

9. Interval appointment

Each row can also have interval appointments, which differ from half-sized appointments visually and in that they are always at the top of the row. Interval appointments can be used to show appointments that last for a longer period of time, such as vacations or workshops.

You can opt to hide the space reserved for interval appointments if no such appointments exist for that time period.

10. Appointment

Appointments consist of an icon or picture, a title, and a subtitle. Concurrent appointments are shown one above the other.

There are four types of appointments:

  • Regular: Displayed in two rows. One-row display is also possible if the appointmentsReducedHeight property is set to “true”.
  • Half-size: Always displayed in one row, shows the title.
  • Large: Always displayed in three rows, also shows the description for each appointment (if available).
  • Automatic: The number of rows is determined automatically.
    Appointment Info Rows
    Title only 1 row
    Title + text
    or:
    Title + description
    2 rows
    Title + text + description 3 rows

You can define the colors for different appointment types. Appointments can also be set to tentative.

The control can register a click event on the appointment, but the app development team must define what happens next.

In the Months view, appointments within the same calendar week are combined to save space. The combined appointment shows the number of appointments in the same week. If an appointment takes place between two calendar weeks (for example, from Sunday to Monday), it is not included in the combined appointments for either calendar week.

A list of the appointments in a combined appointment can be shown in a popover. However, this must be implemented by the app team. The control only provides the click event.

If necessary, you can disable combined appointments (property: GroupAppointmentsMode, value: “Expanded”).

Users can copy and paste appointments to a new position in the planning calendar using keyboard combinations (Ctrl/Cmd + drag and drop to the new position).

Planning Calendar Legend

To show the types for days and appointments, the planning calendar uses a specific legend control
(sap.m.PlanningCalendarLegend).

Users open the planning calendar legend using a standard legend button in the toolbar ( ). Like all other actions in the toolbar, the app developer must add the legend button explicitly.

The app team also needs to decide which container to use for the planning calendar legend. We recommend placing the legend in a popover to keep the context. You can also use a dialog, or, if there is sufficient screen real estate, show the legend as dynamic side content.

The planning calendar legend has two non-collapsible sections containing legend elements. By default, these are called Calendar and Appointments. The app developer can configure the section names using the itemsHeader and appointmentItemsHeader properties. If no elements are available for a section, it is not displayed.

The Calendar section contains standard legend items: Today, Working Day, Non-Working Day, and Selected (only in the 1-month view on mobile). The app team must ensure that the Selected element is added to the planning calendar legend when the planning calendar is viewed in 1-month mode in a smartphone size. This is not provided by the control. If any of the standard legend items are not needed, you can switch them off (property: standardItems).

You can also apply colors for special days in the Calendar section. The planning calendar legend does not automatically use the colors defined for special days in the planning calendar – this must be done by the app team.

Guidelines
Ensure that colors are used consistently within your product area.

The Appointments section contains the color values for the available appointment types. The app developer has to define explicitly which color represents which type. The planning calendar legend does not take the color automatically from the planning calendar.

If combined appointments in the calendar are of the same type (in Months view), they take the color of that type. Combined appointments of different types are marked gray. We also recommend adding the gray color for mixed combined appointments to the Appointments section in the legend.

Planning calendar legend
Planning calendar legend
Developer Hint
To prevent waiting time, app developers should load the sap.ui.unified library.

Behavior and Interaction

To create an appointment, the user must trigger an action by clicking the Create button in the toolbar. You can also configure the control to create a new appointment when the user clicks directly on a row.

The user can click the appointment to see further details. The app development team must define what kind of information is then shown. For example, clicking an appointment can trigger a popover with detailed information.

A multi-select toggle can also be provided in the toolbar. This can be used, for example, to select multiple people in order to delete them from the planning calendar.

Various tooltips can be shown, but you should not use them to show additional information because users cannot access this functionality on touch devices.

Depending on the current visible interval, appointments might be smaller and the text cut off. The user can click the appointment to see the details.

View switch

The user can change the calendar view with the select control (dropdown). For example, to get an overview of a whole year, the user selects the Months view. Which view is most useful depends on the average length of appointments and the use case.

Today

The user can trigger this action to go back to the current date/moment.

Back and forward navigation

The arrows allow the user to navigate to the next or previous interval.

Date picker

The user can open a date picker to select the start time for the visible interval. What is shown initially in the picker differs depending on the view.

Snapping Header

The header area of the planning calendar can remain fixed on top of the screen (property: stickyHeader), which allows users to view calendars with a lot of rows without losing the context.

Header snaps to top when scrolling down
Header snaps to top when scrolling down

Drag and Drop

Drag and drop can be used to move appointments (to enable Drag and Drop use property: enableAppointmentDragAndDrop). Moving an appointment automatically changes its start and end times (for example, if an appointment is scheduled from 1:00-2:00 PM, the user can drag it and change the time from 2:00-3:00 PM) . When dragged, the appointment is shown as a ghost element on the mouse cursor. Drop target areas are indicated to the user with a placeholder.

In the “Hours” view, the appointments can be moved to a specific new time, with the placeholder snapping at every 30 minutes. In the “Days” view, the appointment can be moved to a different day. The placeholder indicates the target day. On drop the appointment is moved to that day but keeps its previous start and end hour. The interaction is the same for the “Months” view. The placeholder indicates the target month and, when dropped, the appointment is moved to that month. The start and end hour and start and end day remain the same.

Appointments can be moved between rows. Note that additional coding may be needed to determine whether all calendar users will be able to perform this action.

Users can create new appointments by clicking, dragging and releasing on an empty space in the content area. The control also allows users to change the duration of an appointment by clicking and dragging one side of the appointment container. These two options are only available for desktop devices.

Combined appointments and interval appointments are not draggable.

Drag and drop is only available on supporting browsers.

Drag and drop
Drag and drop

Guidelines

Switching the Row Header

To enable end users to rearrange the planning calendar by switching the row header, you can implement a flexible row header. This is not done by the control and must be implemented by the app development team.

The list items in the row header can be a value of any attribute of an appointment. The appointment attributes are part of app-specific content, so they should be specified by the app development team. The control does not provide default attributes.

Our guideline is to use the select control in the place of the calendar title. The select control will contain all the attributes that can serve as the row header. When a different attribute is selected, the calendar is rearranged accordingly. You can also add a counter after the list items to indicate how many appointments fall into a specific group.

It is also possible to have both the calendar title and select control, in which case you should have first the title and then the select.

On small screen sizes, use select instead of the calendar title. If you want to keep the calendar title, place select in the overflow menu.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Select Dialog

The select dialog enables users to select one or more items from a comprehensive list. The select dialog comes with a list of entries and a search field to filter the list.

A more enhanced dialog for single selection and multiselection is the value help dialog as it offers range selection and excluding functions.

Usage

Use the select dialog if:

  • Users need to select one or more entries from a comprehensive list that contains multiple attributes or values.

Do not use the select dialog if:

  • Users need to pick one item from a predefined set of options that contains one attribute or value only such as languages. In this case, consider using the combo box or select instead.
  • Your use case requires more enhanced functionalities such as a selection based on ranges. For the selection of values, consider using the value help dialog instead.
  • Your use case requires tabs, filters, or an Add New functionality in the select dialog. In this case, use a standard dialog instead.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

The display of the select control depends on the device. On phones, the selection list takes up the whole screen. On desktop and tablet devices it appears as a popover.

Size S

Single select dialog in full screen on smartphone
Single select dialog in full screen on smartphone
Multi-select dialog in full screen on smartphone
Multi-select dialog in full screen on smartphone

Size M

Single select dialog on tablet
Single select dialog on tablet
Multi-select dialog on tablet
Multi-select dialog on tablet

Size L

Single select dialog on desktop
Single select dialog on desktop
Multi-select dialog on desktop
Multi-select dialog on desktop

Components

Dialog Header

You need to set the title of the dialog header (1). We recommend the following form:

Single selection

Select

Example: Select Product

Multi-selection

Select

Example: Select Products

Search

The first element in the dialog is a standard search field (2).

Info Toolbar

The info toolbar (3) is only available in multi-selection mode. It shows the number of selected items in the following form:

Selected :

Example: Selected Products: 2

Content

The content area (4) can be filled with any list content inherited from the list item base, such as standard list items, display list items, and feed list items. You can set the content to be displayed as grouped.

Button Toolbar

The button toolbar (5) contains two buttonsSelect and Cancel. Select takes over the selection, while Cancel resets the selection to the state it was in when the dialog was opened.

Components of the select dialog. Left: single select, right: multi-select
Components of the select dialog. Left: single select, right: multi-select

Behavior and Interaction

The select dialog can be called up from any control. The most common trigger is an input field with selection icon, also known as a “value help field”, or F4. Alternative triggers are buttons or icons, which add items to an existing list or the infobar in the master list in order to apply a contextual filter.

Single Select

Once users select an entry, the select dialog is closed and the selected entry is taken over. If applicable, the entry is displayed in the field from which the dialog was triggered.

Multi-Select

In the multi-select version of the select dialog, checkboxes are provided for choosing multiple entries. The selection is taken over when the user closes the dialog via OK. Cancel closes the dialog without taking over the selected values. An infobar indicates the number of selected items.

Search

The user can search items.

Resize and Drag Dialog

You can make the select dialog resizable and draggable by setting the corresponding properties (also called resizable and draggable) to “true”.

A resizable dialog makes sense if the items inside have long names or descriptions.

A draggable dialog allows users to see the app content behind the dialog.

Guidelines
Both features are optional. However, even if you only need one, always set both of them to “true” to ensure consistency.

Guidelines

List Options

If you need to indicate that none of the selection options are selected, or you need to allow the user not to select an option, provide (None) as an option and place it at the beginning of the list.

If you need to indicate that all items apply (for example, as a list filter), provide All as an option and place it at the beginning of the list.

Select list with '(None)'
Select list with '(None)'

Search Behavior

Two types of search behavior are available:

(1) A live search, also known as “search-as-you-type” (property: liveChange), which is triggered by each character that the user enters or deletes.

(2) A manual search, which is triggered explicitly after the user enters text in the search field and clicks the Search icon or presses the ENTER key.

Although app developers need to decide themselves which search to use, we recommend implementing the live search whenever possible. Use the manual search only if the amount of data is too large and your app would otherwise run into performance issues. For more information, check out the article on search.

Reset/Remember Selections

By default, the selection is reset when the dialog is closed. This allows users to make a new selection when they reopen the dialog and makes sense when users need to add multiple items to a table.

Selection is reset after the dialog is closed
Selection is reset after the dialog is closed

However, if your use case requires selections in a dialog to be remembered so that the user can make corrections, you can set the rememberSelections function in the select dialog to “true”. When users exit the dialog by clicking Cancel, the selection is then restored to the state it was in when the dialog was opened.

Selection is remembered after the dialog is reopened
Selection is remembered after the dialog is reopened

This also works in single-select dialogs. There, if users click the remembered item again, the dialog closes and they do not have to explicitly click Cancel.

Infobar

In multi-selection mode, an infobar shows the number of selected items. Use the following format:

Selected: [Number of selected items]
Example: Selected: 2

Note that the infobar is not “sticky”. When the user scrolls down the list, the infobar scrolls off the screen.

Infobar States

The infobar has two states – active and non-active (non-clickable). For more information see Infobar States.

Infobar - Active state
Infobar - Active state
Infobar - Non-active state
Infobar - Non-active state

“Clear” Button

The Clear button allows users to clear all the selected items. By default, the button is not shown. To display the button, set the showClearButton property to “true”.

Select dialog with 'Clear' button
Select dialog with 'Clear' button

Content

By default, the select dialog comes with a growing feature (property: growing = “true”). We recommend disabling the growing feature and setting this property to “false”. This ensures that all items in the table are loaded at once, and that the “Items selected” count, the search, and select/deselect features all work properly.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Feed and Notes

Information
The picture of a person is supposed to be displayed in a circle as described in the avatar article. The images of this article will be updated shortly.

Feeds and notes are commonplace in many SAP Fiori applications. The sap.m.FeedInput control allows users to input and post plain text, while the sap.m.FeedListItem control handles and displays this text. Both can be used individually, but they also complement each other well to create a simple feed or notes control.

Usage

Feed Input

Use the feed input if:

  • A user needs to input small amounts of text without formatting.
  • You expect multiple instances, such as notes or feed entries.

Do not use the feed input if:

  • The user needs to format the text (rich text editor).
  • You need only a single text box instance. In this case, use the text area (for multiple lines) or the text control (for a single line).

Combination of Both Controls (as Feed or Notes Control)

Use both controls if:

  • You need a feed to show textual posts.
  • Your users need to input notes.

Do not use both controls if:

  • You expect extensive social interaction in the feed.
  • Users need to reply at item level instead of creating a new post.
  • You want to display SAP Jam feeds.

In these cases, use the social timeline instead (requires SAP Jam).

Responsiveness

Due to their responsive behavior, both controls can be used in small and large view ports or screens.

For better usability, we highly recommend that you do not stretch the controls across the full width on large screens – 2/3 or even 1/2 works just fine. This can easily be achieved using the grid layout .

Feed – Size S
Feed – Size S
Feed – Size M
Feed – Size M
Feed – Size L
Feed – Size L

When the width of the available space falls below 25 rem (for example, in portrait mode on smartphones), the two controls respond as follows:

  • If a user image previously appeared in the feed input, it will be omitted in narrow screens to give the text field more space.
  • If there is no user image, there will be no visual change.
Feed input – Responsiveness
Feed input – Responsiveness

In the feed list item, the user’s name, image, and the time stamp move on top of the text. If there is no image, the name and time stamp are left-aligned together with the text.

Feed list item – Responsiveness – With image
Feed list item – Responsiveness – With image
Feed list item – Responsiveness – Without image
Feed list item – Responsiveness – Without image

Layout

Feed Input

The feed input consists of:

  • A text input field with a placeholder (input prompt)
    Example: Add a comment
  • A Send button
  • An optional user image

You can also choose not to show user images at all. In this case, the size of the input area increases automatically.

Feed input – Layout – With user image
Feed input – Layout – With user image
Feed input – Layout – With generic user image
Feed input – Layout – With generic user image
Feed input – Layout – Without user image
Feed input – Layout – Without user image

Feed List Item

The feed list item consists of the user’s name and an optional picture of the user who wrote the note or update. The name can contain a link that triggers a quick overview of the user’s profile data. The actual text written by the user follows the name. Below it is a separate byline that can contain a time stamp and an attribute in the form of free text. This allows you to put in your own attribute, such as Approval, Internal, or External. Both the time stamp and the attribute are optional.

If the name is a link, the picture should also be linked with the same attributes.

Feed list item – With user image and linked name
Feed list item – With user image and linked name

If the user does not have a picture assigned, a placeholder is shown instead:

Feed list item – With generic user image and linked name
Feed list item – With generic user image and linked name

The name (and picture) can also be read-only, that is, without a link:

Feed list item – With user image but without links
Feed list item – With user image but without links

If the app does not support user images, they can be omitted:

Feed list item – Without user image but with linked name
Feed list item – Without user image but with linked name

Here, too, the name can be read-only:

Feed list item – Without user image and read-only name
Feed list item – Without user image and read-only name

It’s also possible to display rich text (formatted text) in the feed list item. This feature should be handled with care as it allows for countless custom layouts.

Please see that you use it responsibly and provide your users with a consistent experience. Only deviate from the default layout and font if absolutely required by the use case.

Example use case: Render URLs as links.

Feed list item – Layout – Rich text
Feed list item – Layout – Rich text
Information
The items in the feed list must be homogeneous. This means that they must contain the same layout and visualization. For example, it is not possible to have a feed containing both linked and plain names, or both user images and default images.

Special Case: Multiple Types of Notes

Apps sometimes need to discern between different types of notes. There is an easy way to allow users to choose which type they want to see or add to the list.

You can place a toolbar containing a select control at the top of the feed input control. From there, users can select the type of notes, such as Internal Notes or External Notes. The list of notes must contain only the type selected. If the user adds a note via the feed input, the type must be set automatically according to the selection.

Interaction – Note Types

Components

The feed input and feed list item do not contain subcontrols. However, you can easily combine them to create a simple feed or notes control.

Although the feed input counts as a single control, the input area inherits its behavior from the sap.m.TextArea control.

Behavior and Interaction

Send Message

Initially, the feeder contains a placeholder (input prompt), and the Send button is disabled, with reduced opacity.

Clicking into the input field puts the focus on the field and allows to start typing.

When the user starts to type, the placeholder disappears and the Send button becomes active and more prominent.

If the available width is below 25 rem (for example, in portrait mode on a smartphone), the picture is removed.

To send the text, the user must explicitly click the Send button. Pressing Enter on the keyboard (on-screen or physical) results in a line break.

Feed input – Behavior
Feed input – Behavior

Show More Text

When the text exceeds a certain number of characters (you can overwrite the default value), the rest of the text is truncated and a MORE link appears after the truncated section.

The MORE link indicates the possibility of expanding the section of the feed list item itself. Hovering over the link underlines it.

Show Less Text

When the user expands the text, the name of this link changes to LESS,  but still behaves the same way as before.

Both texts for the “MORE” / “LESS” links can be modified to suit a particular use case.  There is a possibility to use uppercase, lowercase or a mix of them.

MORE link (1)
MORE link (1)
MORE link (2)
MORE link (2)

Feed and Notes in Tables

In tables, users sometimes need to see if an object has a comment (or feed or note) without further navigation, and even be able to add/edit right from the table.

Add an additional column, named according to the type of user input, such as Comment, Note, or Feed.

Place a link inside each cell with the appropriate action (row: Comment, link: Comment/ row: Feed, link: Post).
If there can be more than one item, add a counter after the text as well (see example on the right).

This solution works with every table control.

Feed and notes in tables (1)
Feed and notes in tables (1)

Optional:
Depending on the use case, it might help users if they can see the latest note. The responsive table allows the feed list item (sap.m.FeedListItem) to be used inside a cell.

Reduce the property “maxCharacters” to an amount that your table can handle.
Note that once the maximum number of characters has been reached, a MORE link allows users to expand the text. Technically, this is no problem for the responsive table, but you need to ensure that the layout of your page allows this kind of expansion.

Place a link below the feed list item to allow users to add something (as described above).

Feed and notes in tables (2)
Feed and notes in tables (2)

When the user clicks a link, such as Comment or Note, display a dialog showing all comments (notes, feed entries, and so on) along with possible actions, such as Add or Edit, depending on your use case.

There are several ways to show notes (comments, feed entries, and so on) in a dialog:

  • You can use the feed list item (and feed input) as described in this article.
  • If only one single note is allowed, you can use the text area.
  • For a large feed, you can use the timeline control (SAP Jam is required for social features).

Actions On Feed List Items

Applications can define actions that users can perform on individual feed posts. The two most typical actions are Edit and Delete. Other actions can be introduced as required by the use case. To keep the feed as lightweight as possible, don’t overwhelm users with too many actions or complicated actions (max. 5 per post).

Interaction - Actions
Interaction - Actions

Styles

By default, feed entries are separated by divider lines. We recommend that these separators remain enabled, since they help distinguish between individual posts. However, if your list is expected to hold only a handful of entries, you can disable the separators by setting the showSeparators property at list level (not at list item level) to none.

Guidelines

Because the feed list item is built on the basis of the standard list item, it inherits multiple properties that may not make sense in a feed use case.

Use only properties that are described in this article. Especially making the entire feed list item clickable can lead to functional issues and usability problems.

Don’t stretch the feed input or the feed list items across large screens (size L and beyond). This will have a negative effect on usability and readability. Instead, only use 1/3 or even 1/2 of the screen. Implement this with the grid layout .

If you display formatted text (rich text) in the feed list item, use formatting that is beneficial to users, not decorative formatting. Use formatting responsibly, and provide your users with a consistent experience. Deviate from the default layout and font only if absolutely required by the use case (example: render URLs as links).

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

  • No links.

Implementation

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
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 L
Single planning calendar - Size M
Single planning calendar - Size M
Single planning calendar - Size S
Single planning calendar - Size S

Components

The single planning calendar consists of the following components:

  1. Header
  2. Toolbar
  3. View switch
  4. Navigation
  5. Date strip
  6. All-day appointment
  7. Timeline
  8. Appointment
  9. Calendar grid
  10. Now marker
Components of the single planning calendar
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
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 10 days - size L
Custom view 3 days - size S
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.

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
Appointment structure
Now marker - Current time replaces the full hour
Now marker - Current time replaces the full hour

Single Planning Calendar Legend

You can highlight special days within the calendar. A legend is used to define the meaning of the highlights. Users open the legend using the legend icon button in the toolbar (  ). Like all other actions in the toolbar, the app developer must add the legend button explicitly.

For details, see the legend sections for the Planning Calendar and Calendar.

Guidelines
Ensure that colors are used consistently within your product area.
Single planning calendar legend
Single planning calendar legend

Behavior and Interaction

Date Picker

The visible period is indicated with the date interval link in the navigation. Clicking the link opens a date picker, which helps the user to navigate quickly to a specific day or week.

Creating an Appointment

We recommend offering a Create action in the toolbar.

The UI for creating the appointment must be implemented at app level. The control provides only the underlying functionality for creating appointments. For most use cases, a dialog works best and is recommended (see sample dialog below).

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).

Working Hours

You can opt to set working hours in the single planning calendar (properties: startHourendHour). 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).

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
Drag and drop into the all-day appointments area
Drag and drop into the all-day appointments area
Drag and drop from 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

Implementation

Smart Field

The smart field creates different user input controls and their read-only equivalents based on an OData (Open Data Protocol) service and its annotations. It comes with additional built-in features, such as autocomplete and suggestions, value help dialogrecently used and recommended valuesvalidation, and message handling.

Information
The smart field is only available for OData version 2.

When to Use

Use the smart field if:

  • You use an OData service for your app (OData version 2 only).
  • The feature set of the smart field fits your app. In this case, the smart field is faster to implement.
  • You use the smart table and your app is not performance-critical. The smart field offers more flexibility than the controls provided directly by the smart table, especially for editing.
  • You use a smart form.

Do not use the smart field if:

  • You use a different technology to OData version 2. Use the corresponding controls directly.
  • You need a different control for entering or displaying data, such as multi input, a multi combo box, step input, a radio button, or a title. In this case, use the corresponding control directly.
  • You need a different dialog for offering value help, such as the select dialog or table select dialog.
  • You use the smart table and your app is performance-critical. In this case, the controls offered directly by the smart table offer less flexibility but better performance.

Components

The smart field consists of a basic UI element and an optional label. The following UI elements are available:

 For details, see the corresponding guideline topics. 

User Input Control

The smart field chooses the control automatically based on the data type (Edm type) and annotations of the OData service and additional properties. The following controls are used:

Read-Only Edit Edm Types / Annotations / Properties Comment
Single-line text Text Input field Edm.String

Configuration: controlType, value: input

Combo box Edm.String

Configuration: controlType, value: dropDownList

Select Edm.String

Configuration: controlType, value: selection

Multi-line text Text Text area Edm.String

MultiLineText

Decimal numbers Text

Object number

One or two input fields
(for number and unit)
Edm.Int16, Edm.Int32, Edm.Int64,
Edm.SByte, Edm.Byte,
Edm.Single, Edm.Float, Edm.Double,
Edm.Decimal
Precision, Scale
Status information Object status Edm.String

criticality, criticalityRepresentationType

Text and ID Text

Object identifier

Object status

Input field TextArrangement

controlProposal

displayBehavior

textInEditModeSource, sap:text,
fetchValueListReadOnly

The following patterns can be selected via displayBehavior:

  • Text (ID)
  • ID (Text)
  • Text
  • ID
Links
(with/without quick view)
Link

Smart link

Edm.String

IsURL, url

semanticObjectController

Dates Text Date picker Edm.DateTime

sap:display-format=”Date”

IsCalendarDate

Configuration: controlType

Dates and times Text Date/time picker Edm.DateTime

Edm.DateTimeOffset

Times Text Time picker Edm.Time
Fiscal periods Text Input field IsFiscalYear, IsFiscalPeriod,
IsFiscalYearPeriod,
IsFiscalQuarter, IsFiscalYearQuarter,
IsFiscalWeek, IsFiscalYearWeek,
IsDayOfFiscalYear
Amounts with currencies Text One or two input fields ISOCurrency or sap:unit with sap:semantics=”currency-code”
Phone numbers Text Input field IsPhoneNumber
Email Text Input field IsEmailAddress
Boolean Checkbox Checkbox Edm.Boolean
Text Combo box Edm.Boolean

valueList

displayBehavior

The text in display mode can be influenced via displayBehavior:

  • Yes/No
  • True/False
  • On/Off
Guidelines

  • Set a default value whenever appropriate (annotation: text, property: value).
  • To show a static unit of measurement, use a description (annotation: text).
  • To display a text and ID in the same place, use the format Text (ID) wherever possible. Use another format only if displaying the text doesn’t make any sense. Be careful when using the text arrangement options in tables: end users will only be able to sort, group, or filter based on the ID, even if the ID isn’t visible.
  • If you are not using the smart field within a smart form or smart table, label the smart field with a smart label (annotation: label, properties: textLabel, showLabel). The standard label doesn’t know the inner structure of a smart field.
  • You can set a tooltip (annotation: QuickInfo), but this should usually be avoided. See Using Tooltips.
  • If data entry is expected in a specific format, set a placeholder (property: Placeholder).

Developer Hint
Performance: Using the TextArrangement annotation to display both the text and ID (in any order) triggers two requests to the back end.

Behavior and Interaction

Context

You can use the smart field in different contexts
(property: controlContext):

  • Standalone
  • Within a form (depending on the form layout)
  • Within a table (depending on the table type)

The context influences:

  • Labels: In most cases, forms provide the label automatically.
  • Empty values in display mode: In forms, empty values are shown as a dash. In tables, the field remains blank.
  • How units of measurement are displayed
Guidelines

  • If the width is not handled by the context, set a meaningful width for the smart field, based on the expected data (property: Width).
  • If you use a “standalone” smart field  in a form-like arrangement, use a dash to show an empty value in display mode.

Switching Between Edit and Display Mode

Switching between edit and display mode can be controlled manually (annotation: FieldControl, property: editable) or automatically by the containing smart form or smart table (property: contextEditable).

Smart field as a select with 'required' indicator in edit mode
Smart field as a select with 'required' indicator in edit mode
The same smart field in display mode
The same smart field in display mode
Guidelines

  • Define which fields should be editable (annotations: updateable, creatable, updateable-path, InsertRestrictions, UpdateRestrictions, computed, immutable, fieldControl, fieldControlType).
  • For fields with a unit of measurement, define whether the unit of measurement is editable or static (annotation: FieldControl, property: uomEditable).
  • Make sure that the full text is shown in display mode (property: wrapping), unless this is handled differently for the corresponding context (for example, see guidelines for content in the grid table).
  • When you display the text and ID, the smart field automatically displays both values in display mode, but only the ID in edit mode (annotation: TextArrangement). In most cases, it makes sense to also display both values in edit mode (annotation: sap:text, property: textInEditModeSource, aggregation: Configuration with property: displayBehavior).

Suggestions and Value Help

You can enable suggestions for controls that offer this feature (property: showSuggestions). The list of suggestible values must be provided (annotation: ValueList or ValueListWithFixedValues only for Edm.String, property: entitySet). This list can contain several attributes and is also used for the value help dialog. You can restrict the number of attributes from this list to be shown as suggestions, while all attributes are shown within the value help dialog.

Autocomplete is enabled automatically.

For input fields, the value help dialog is also created automatically. Hide it if it is not needed (property: showValueHelp). The table in the value help dialog can be filled with initial content (annotation: ValueList, property: fetchValues, sap.ui.comp.smartfield.Configuration, property: preventInitialDataFetchInValueHelpDialog)

Both the value help dialog and the suggestion list can be prefiltered (annotation: ValueList, property: valueListParameterIn). The selected items can be used to prefilter other fields (annotation: ValueList, property: ValueListParameterOut). The corresponding filter settings are visible. “Invisible” prefiltering is also supported. To use this option, provide the exact matching filter value (Common.ValueListParameterConstant).

If a value has been entered in the smart field, this value is transferred to the search field of the value help dialog automatically. In the value help dialog, individual values can be valid, deprecated, or revoked. Revoked values are hidden from the value help (annotation: IsConfigurationDeprecationCode).

The following controls are used to offer suggestions or value help:

Smart field as a combo box
Smart field as a combo box
Smart field as an input field with suggestions, auto complete, and a value help button
Smart field as an input field with suggestions, auto complete, and a value help button
The automatically generated value help dialog for the same smart field
The automatically generated value help dialog for the same smart field

Recently Used Values

Input fields, combo boxes, and selects can provide up to five recently used values automatically on focus if suggestions or value help are available. This can be turned on or off per field (property: historyEnabled). Recently used values are shown by default for input fields, but not for combo boxes and selects.

Guidelines
Do not show recently used values for a field if:

  • There are only a small number of options.
  • The field contains personal sensitive data (annotation: IsPotentiallySensitive).
  • It is unlikely that the same values will be selected again and again.

Recommended Values

In addition to recently used values, a smart field can show recommended values (annotation: RecommendationState).

The corresponding smart field is highlighted and/or prefilled:

  • If no recommendation is available or the current user input matches the recommendation, the smart field is shown in the default state.
  • If a recommendation is available and there is no user input, the smart field is shown in the information state.
  • If a recommendation is available and it differs from the current user input, the smart field is displayed in the warning state.

The recommended values are shown as soon as the user focuses on the smart field.

Validation

The smart field offers the following validations automatically:

  • Validation for required fields: This can be done on the client or server side (property: clientSideMandatoryCheck, annotation: Nullable).
  • Validation for a group of fields: Validation is triggered when the focus moves outside a group of fields, rather than when a single field loses the focus. A group is defined by all smart fields that share the same field group ID (property: fieldGroupIds).
  • Validation for the maximum length of user input: Validation is triggered when a field loses the focus or the ENTER key is pressed (property: maxLength).
  • Validation for combo boxes: Checks if the value entered is available in the dropdown list (property: fixedValueListValidationEnabled).

The validation result is indicated by a value state (property: showValueStateMessage).

When the user edits a smart field showing a text and ID, you can allow any kind of input to avoid unnecessary validation issues (annotation: ValueListNoValidation).

Examples:

  • Allowing the user to enter additional values (which are not in the suggestion list)
  • Typing a text instead of an ID to filter down the suggestion list
  • Using the smart field in a draft
Automatic validation
Automatic validation

IDs

The smart field offers automatic validation for number-only ID fields (annotations: IsDigitSequence or sap:display-format="NonNegative"):

  • It checks for non-negative numbers.
  • It shows values containing only “0” digits as empty.
  • It does not show leading zeros.

Units

For decimal number fields and for fields that show an amount with a currency, you can add a unit of measure  (annotations: unit, sap-unit with sap:semantics="unit-of-measure" or sap:semantics="currency-code", property: uomVisible). In display mode, the unit is added to the corresponding number. In edit mode, the unit is shown either as text or, if editable, as a second input field (properties: uomEditable, uomEnabled).

Smart field showing an amount with a currency in display mode
Smart field showing an amount with a currency in display mode
The same smart field in display mode
The same smart field in display mode

Sensitive Data

Sensitive data, such as passwords, can be masked. The text is then replaced with asterisks (annotations: IsPotentiallySensitive, masked).

Capitalizing Text Input

Text input can be capitalized automatically (property: IsUpperCase).

States

Smart fields support the following states (annotation: fieldControl):

  • Editable or display only (additional annotations: updateable, creatable, updatable-path, InsertRestrictions, UpdateRestrictions, property: editable)
  • Enabled or disabled
  • Visible or hidden (additional annotations: property: visible, annotation: sap:visible)
  • Required: If set, the smart field must contain a value when validated. This is indicated by an asterisk next to the corresponding label (additional annotation: Nullable, property: mandatory).

The following states for a unit of measurement can be set independently of the corresponding field:

  • If editable, a unit of measurement can be enabled or disabled (property: uomEnabled)
  • The unit of measurement can be visible or hidden (property: uomVisible)
Developer Hint
In the SAPUI5 SDK API Reference for the smart field, the display only state is referred to as read only.

Dependencies between Smart Fields

If the content of a smart field is changed, you can trigger additional changes to other fields on the UI (annotation: SideEffects).

Content Alignment

You can change the horizontal alignment of the text within any kind of input field  (property: textAlign).

Guidelines
Follow the alignment rules for the respective context (responsive table, other tables, form). If you are using the standalone option for the smart field (without a context), apply the rules for the corresponding input fields.

Responsiveness

The smart field acts exactly like the embedded controls. For details see:

Top Tips

  • Always label a smart field if it is not inside a table context.
  • Use suggestions with autocomplete whenever possible and meaningful.
    • Do not show suggestions if there are only a few choices.
    • Use recently used values as appropriate.
    • Reduce the number of attributes shown in the suggestion list to a maximum of 4 or 5.
  • Make use of validation features.

Properties

The following properties, aggregations, and associations are available for sap.ui.comp.smartfield.SmartField:

  • The property: expandNavigationProperties is experimental. Do not use it.
  • The property: importance hides the field if the smart field is placed in a smart form, depending on the importance setting of the smart form. End users have no possibility to show the corresponding fields again. Do not use this property.
  • The property: jsontype is deprecated. Do not use it.
  • The property: name is used in HTML forms that send data to the server via “Submit”.
  • The property: uomEditState is for internal use only. Do not use it.
  • The property: proposedControl is deprecated. Do not use it.
  • The property: textDirection provides support for reading directions in different locales.
  • The aggregation: controlProposal is deprecated. Do not use it.
  • The association: ariaLabelledBy can be used for linking additional labels to the smart field.

Related Links

Elements and Controls

Implementation

P13n Dialog

Intro

The p13n dialog control provides a dialog for tables that allows the user to personalize one or more of the following attributes:

  • Columns (visibility and order of columns)
  • Sort (sorting of table values)
  • Filter (filtering of table values)
  • Group (grouping for specific attributes)

These tabs can be shown in any combination, as the use case requires.

The P13n dialog is intended for complex tables with a large number of columns and the need for complex queries for sorting, grouping, and filtering.
For simple tables, see view settings dialog and table personalization dialog.

The P13n dialog can be triggered in the table toolbar using the corresponding buttons in the top right-hand corner of the table.

The dialog is shown centered, either as a dialog (on desktop and tablet devices) or as a full-screen dialog (on mobile devices).

Dialog buttons within the table toolbar
Dialog buttons within the table toolbar

Usage

Use the P13n dialog if:

  • The user is able to personalize more than 20 or so columns.
  • You need several functions for sorting, grouping, and so on.
  • You are using the analytical table.
  • Complex queries have to be built for the relevant table.

Do not use the P13n dialog if:

  • The user is able to personalize fewer than about 20 columns.
  • You only need a simple column show/hide feature.

Responsiveness

The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), the dialog is shown as a dialog. For size S (smartphones), the P13n dialog is displayed as a full-screen dialog.

Size S – Columns
Size S – Columns
Size M
Size M
Size L
Size L

Components

The P13n dialog consists of four different tabs that can be used separately or combined, as required by the use case:

  • Sort
  • Filter
  • Group
  • Columns

App developers can add more tabs manually.

Behavior and Interaction

Columns

The first tab is the Columns tab. It allows the user to change the table columns that are shown and the order in which they are displayed.

The list contains all of the table’s possible columns in the form of list items with checkboxes. The checkboxes of the currently displayed columns are selected.

Another button next to the search field in the table toolbar allows the user to toggle between showing all columns and only those that are currently selected in the list.

Show/Hide

To show or hide a column, select or deselect the appropriate checkbox.

Reorder

To change the order of the columns, simply mark one list item and use the buttons on the right-hand side of the table toolbar to move them up or down. The order of the columns from top to bottom corresponds to the order on the table from left to right.

Search

If the table has numerous columns, the user can use the search field in the table toolbar to find a specific column more quickly. As soon as the user enters the first letter, the resulting columns are displayed instantly.

Column settings in the P13n dialog
Column settings in the P13n dialog

Sort

The second tab is the Sort tab, which allows the user to sort the table content according to the chosen attributes, and also in either ascending or descending order.

The sort criterion consists of two input fields. In the first field, the user can choose a column by which the table is to be sorted. In the second field, the user chooses the sort order (ascending or descending).

For more complex sorting needs, the user can add the required number of criteria by clicking the plus “ ” sign at the end of the line.

The order of the criteria is exactly the same as the order in which sorting is applied to the table.

Sort settings in the P13n dialog
Sort settings in the P13n dialog
Information
Using the sort feature on column headers replaces ALL sort options in the dialog!

Filter

The third tab is the Filter tab, which allows the user to filter the table information according to specific criteria.

The filter criteria can be included or excluded in the relevant section of the filter. There is only one operation dropdown for both include/exclude operations.

Column

In the first input field, the user selects the column to be filtered. Any of the columns can be selected; even those that are not currently visible.

Option

The second field offers an operator for specifying the filter in more detail. The operators that are available depends on the data type of the selected column.

Filter tab in the P13n dialog
Filter tab in the P13n dialog

String (Text)

  • between
  • contains
  • equal to
  • begins with
  • ends with
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Number

  • between
  • equal to
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Date

  • between
  • equal to
  • after
  • on or after
  • before
  • before or on

Boolean (true / false)

  • equal to

The only available operator for excluding values from the filter results is equal to.

Value

The last field contains the value by which the selected column is filtered. The kind of input field that is provided depends on the data type of the selected column.

Two or even more fields can be provided as required by the use case.

For more complex cases, the user can add filters by clicking the plus “ ” button or remove them by clicking the Remove button at the end of each filter item.

Information
If there is a filter bar, use its filter functionality and deactivate the filter feature of the P13n dialog.

Group

The last tab is the Group tab, which enables the user to group the table data by one or more columns.

In the first selection field, all columns are provided for selection. The user can select a checkbox on the right of the column selection field if the selected field is to be displayed as a column anyway.

For more complex grouping scenarios, the user can add more grouping options by clicking the plus “ ” button on the right-hand side of each grouping line. This option only works with the analytical table.

The grouped table shows the selected field as the group header, which can be expanded or collapsed.

Under the group headers, all subgroup headers and all applicable table entries are displayed.

Group tab in the P13n dialog
Group tab in the P13n dialog
Information
To group by a specific column, that particular column must be marked as visible on the Columns tab!

Guidelines

For opening the dialog from a table toolbar, use different buttons for each function (sort, filter, group, column settings). With each button, open the P13n dialog with just the corresponding tab. Do not display the other tabs.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Calendar

The calendar control lets users select a single date, multiple days, entire week(s), or a date range. The calendar shows all time-related data (year, month, week, day, date) at a glance. It also allows users to navigate directly from one month or year to another, or to display multiple months.

When to Use

Use the calendar if:

  • You want the user to select a single date, multiple days, entire week(s), or a date range.
  • You want to display multiple months at once.
  • The calendar always needs to be visible and prominent.
  • Users need to see the year, month, week, weekday and date at a glance to decide which date to select. For example, a user might want to select a date based on the day of the week.
  • Users might be used to different locale-specific date formats (such as day-month-year or month-day-year). Enabling them to select the date visually using the calendar bypasses format-specific interpretation.
  • You want to highlight special days or hide/disable specific days.

Do not use the calendar if:

  • The user is a power user who has to enter a lot of data fast. In this case, use the date picker.
  • The keyboard is the primary input device. In this case, use the date picker.
  • The available screen space is limited and displaying the calendar permanently would take up too much space.
  • The user’s primary goal is to select a date range. In this case, use date range selection.
  • You want to display a range of weekdays in a single row. In this case, use the calendar date interval.
  • The user wants to compare calendars from different people. In this case, use the planning calendar.
  • The user wants to select combined date and time values. In this case, use the date/time picker.

Components

The calendar can stand alone as a control, but is also part of many other controls, such as the date picker, date/time picker or the date range selector.

By default, the focus starts on the current day, but can be customized to fit the use case.

Calendar with current date and selected date
Calendar with current date and selected date
Clickable areas of the calendar
Clickable areas of the calendar

The control allows you to show or hide the calendar weeks. You can also customize the calendar by defining the start and end of a week, or by defining the earliest or latest date.

Specific days can also be disabled, for example non-working days or public holidays.

Calendar without calendar weeks and with disabled days
Calendar without calendar weeks and with disabled days

Month and Year View

The control offers a day view, month view, year view, or year ranges.

Month view
Month view
Year view
Year view
Year range
Year range

Legend for Highlighted Days

Within the calendar, special days can be highlighted. A legend is used to define the meaning of the highlights. Application development teams are responsible for using the colors consistently within one product area.

Calendar with highlighted days and legend
Calendar with highlighted days and legend

Types

The following calendar types are available:

  • Single day selection: The user can select a single day at a time.
  • Single interval selection: The user can select an interval or one entire week.
  • Multiple day selection: The user can select multiple days, which do not have to be next to each other. It’s also possible to select entire week(s) and a date range.
  • Multiple months: Use this calendar type if users need to see more than one month to make their selection. You can offer single day selection or multiple selection (such as multiple days, entire weeks, or date ranges). We recommend showing no more than two or three calendars at the same time.
Single day selection
Single day selection
Single interval selection
Single interval selection
Multiple day selection
Multiple day selection
Multiple month view
Multiple month view

Behavior and Interaction

The behavior and interaction of the calendar depends on the calendar type. Some interactions are only available for specific calendar types.

Selecting a Single Date

Clicking the date selects it. Clicking the date again deselects it.

Single day selection
Single day selection

Selecting a Single Interval

The user selects a single interval by clicking the first and last day of the date range, which also selects all the days in between. Alternatively, the user can select two different dates and press Shift+Enter twice.

Single interval selection
Single interval selection

Selecting an Entire Week

To select an entire week, the user clicks the number for calendar week (if displayed). Alternatively, the user can select one day within the week and press Shift+Space simultaneously.

Selection of an entire week by clicking on the calendar week
Selection of an entire week by clicking on the calendar week

Selecting Multiple Days

Multiple days are selected by clicking the desired days individually. Clicking the selected days again deselects them.

Selection of multiple days
Selection of multiple days

Changing Months

If the current month is selected, the view changes to the month view and the user can change the month. By clicking a month, the user changes the month and the view changes back to the day view.

Changing the month using the month view
Changing the month using the month view

Clicking the arrow in the day view of the calendar shows the next month of the same year.

Changing the month using the arrow
Changing the month using the arrow

Changing Years

Clicking the current year changes the view to year view. When the user selects a year, the view changes back to the day view.

Changing the year using the year view
Changing the year using the year view

Clicking the arrow in the month view shows the same selected month in the next year.

Changing the year using the arrow
Changing the year using the arrow

Clicking the year range changes the view to year range view. When the user selects a year range, the view changes back to the year view.

Changing the year range in year view
Changing the year range in year view

Clicking the arrow in the year view shows the next year range, changing in increments of 20 years.

Changing the year range in year view
Changing the year range in year view

Clicking the arrow in the year range switches to the next 180 year span.

Changing the year range
Changing the year range

Responsiveness

Use the calendar within a responsive layout container. The calendar control itself is not responsive.

When using the multiple month view, the calendar adapts to the size of the screen. On small screens, only one calendar is displayed.

Related Topics

Elements and Controls

Implementation

Table Select Dialog

Table select is a commonly-used dialog that helps users to make a selection from a comprehensive table containing multiple attributes or values. With the dialog, users are also able to access additional information about the objects in the table without needing to select them first.

The dialog provides a responsive table layout with additional search, filter, and selection functionalities in the header. A footer toolbar provides actions for canceling or confirming the process.

Usage

Use the table select dialog if:

  • You need to help users select one or more items from a comprehensive list that contains multiple attributes or values.

Do not use the table select dialog if:

  • You need to help users pick one item from a predefined set of options that contains only one value. In this case, use the dropdown box instead.
  • You need to help users with query-based range selection and enhanced filter options. In this case, use the value help dialog instead.
  • Your use case requires tabs, filters, or actions in a select dialog.In this case, use a standard dialog instead.
  • Your use case only requires filtering without selection. In this case, use the filter toolbar instead.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

The table inside the table select dialog behaves like the responsive table. On smaller screens, the columns wrap and build a list that shows all the information. All other elements in the control are also responsive.

On bigger screens, the table select dialog also provides columns
On bigger screens, the table select dialog also provides columns
The table in the dialog is responsive and wraps on smaller screens to show a list
The table in the dialog is responsive and wraps on smaller screens to show a list

Behavior and Interaction

The table select dialog can be called up from any control. The trigger is usually a button with a selection icon in an input field, or an Add button in a toolbar.

Triggers

Input Trigger

This trigger can be useful if users need to select, for example, one customer from a large customer register.

Example of a trigger: the selection icon in the input field
Example of a trigger: the selection icon in the input field

“Add” Button

This trigger can be useful if users need to add an item to a list. For example, the dialog could help users select the product from a large product catalog. Clicking Select in the footer toolbar of the dialog adds the selected products to the list.

“Clear” Button

The Clear button allows users to clear all the selected items.

Example of a trigger: 'Add' button in a table
Example of a trigger: 'Add' button in a table

Sticky Header

The column headers and info toolbar in the table select dialog are “sticky”, which means that they stay fixed on top when scrolling (sap.m.Table, property: sticky).

Information
The “sticky” feature has some browser limitations, and is not supported in Internet Explorer and in Microsoft Edge versions older than 41. In these browsers, the headers of the table select dialog will not be sticky.
Example of sticky headers
Example of sticky headers

 

Single Select

The single-select version does not need a Select button in the footer toolbar because the selected entry is taken over and closed as soon as a user selects an item from the table. If applicable, the entry is displayed in the field from which the dialog was triggered. Alternatively, a toast message can be shown if necessary.

Multi-Select

The multi-select version of the table select dialog provides checkboxes for users to choose multiple items. The blue infobar above the table indicates the number of selected items. The selection is taken over when the user closes the dialog via the Select button in the footer toolbar. Clicking Cancel closes the dialog without taking over the selected values.

Remembering Selections

If selections need to be memorized in order to help users make corrections, you can set the RememberSelections property to true. This restores the selection to the state it was in when the dialog was last opened as soon as users exit the dialog via Select or Cancel. The interaction flow of the RememberSelections property is shown and explained in the select dialog article.

Grouping

The list can also be displayed as grouped. Group headers divide the table into segments. A pregrouped table is useful for tables with many entries, which can be sorted by a single attribute.

Table select dialog with group headers
Table select dialog with group headers

Resize and Drag Dialog

You can allow users to resize and drag the table select dialog by setting the resizable and draggable properties to “true”.

  • A resizable dialog makes sense if the items within the dialog can have long names or descriptions.
  • A draggable dialog allows users to see the app content behind the dialog.
Guidelines
Both features are optional. However, if you only need one, always set both properties to “true” for consistency reasons.

Guidelines

Set the information provided in the table select dialog from top to bottom as follows:

Dialog Header

Use the following format for the dialog header:

  • For single selection: Select [Business Object]
    Example: Select Product
  • For multiple selection: Select [Business Objects]
    Example: Select Products.

Search

The first interactive element in the dialog is a standard search field. Two types of search behavior are available:

  • live search, also known as “search-as-you-type,” which is triggered by each character that the user enters or deletes.
  • A manual search, which is triggered explicitly after the user enters text in the search field and clicks theSearch icon or presses the ENTER key. As soon as the user hits the Search button, a Delete icon appears at the end of the input field to delete the keyword and cancel the result list.

App developers need to decide which search to use. We recommend implementing the live search whenever possible. Use the manual search only if the amount of data is too large and if your app would otherwise run into performance issues. For more information, check out the article on searching.

Infobar

In multi-selection mode, an infobar shows the number of selected items. Use the following format:

[Business Objects] Selected: [Number of Items]
Example: Products Selected: 2

“Clear” Button

The “Clear” button for clearing all the selected items is optional. By default, the button is not shown. To display the button, set the showClearButton property to “true”.

Content

The content area provides a table. This behaves like the responsive table, so the columns wrap on smaller screens and display a list.

By default, the table select comes with a growing feature (property: growing = true). We recommend disabling the growing feature and setting this property to “false”. This ensures that all items in the table are loaded at once, and that the “Items selected” count, the search, and select/deselect features all work properly.

Footer Toolbar

In the multi-select version, the footer toolbar contains the Select and Cancel buttons. Select takes over the selection, while Cancel resets the selection to the state it was in when the user opened the dialog.

In the single-select version, only provide Cancel in the footer toolbar because the dialog takes over the selection as soon as the user chooses one.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Filter Bar

The filter bar filters item lists and tables according to various filter criteria. You can use it for both simple and complex lists, regardless of their size. To handle complex lists with multiple filters, the filter bar provides predefined, customizable filter sets (variants).

The smart filter bar is closely related to the filter bar, as it covers the same use cases. The difference is that the smart filter bar uses annotations to create a filter bar.

Filter bar within the dynamic page
Filter bar within the dynamic page
Information
The filter bar now supports the dynamic page. Do not use the filter bar in the sap.m.Page for new SAP Fiori apps. For more information on the differences, see the filter bar guideline for version 1.52.

Responsiveness

Because tables appear in many apps, from simple to complex ones, the filter bar needs to run on all form factors. While the main concept of the filter bar remains stable across the devices, its responsive design adapts the control’s behavior to match the ability of each device.

Size S (Smartphones)

Expanded filter bar - Size S
Expanded filter bar - Size S
Collapsed filter bar - Size S
Collapsed filter bar - Size S
Filter dialog - Size S
Filter dialog - Size S

Size L (Desktop)

Expanded filter bar - Size L
Expanded filter bar - Size L
Collapsed filter bar - Size L
Collapsed filter bar - Size L
Filter dialog - Size L
Filter dialog - Size L

Layout

Filter Dialog

The filters inside the filter dialog are arranged in a vertical linear layout. If filter groups are maintained, the filters are visually grouped in sections, with the filter group name at the top. A link at the end of each group allows the user to add or remove filters from that group. The link text is Change Filters if at least one filter is activated, indicating that filters can be added or removed. If no filters have been set for the group, the link text is More Filters, indicating that more filters can be added.
The first group is called “Basic” and contains the preset filters that come with the app. A checkbox next to each filter enables the user to show the corresponding filter on the expanded filter bar. If the checkbox is selected, the filter is shown on the expanded filter bar. If the checkbox is not selected, the filter is only visible within the filter dialog. In both cases, the filter is active if a value is entered.
The vertical layout of the filter dialog remains stable across all devices. To ensure a clean grid layout appearance, the size of the widest input field is inherited by all other filters.
Filter dialog (size L)
Filter dialog (size L)

Expanded Filter Bar

The expanded filter bar arranges the input fields in a simple horizontal linear layout. If the browser’s window size is reduced or the filters exceed the first line, a simple mechanism opens a new line of filters. The height of the expanded filter bar is not limited and adjusts to accommodate the filters that need to be shown. The label is always above the input field. As in the filter dialog, the size of the widest input field is inherited by all other filters. This avoids having unstable and busy-looking grid layouts.
Filter bar (size L) with one row of filters
Filter bar (size L) with one row of filters
Filter bar (size L) with more than one row of filters
Filter bar (size L) with more than one row of filters
Filter bar (size S) with vertical filters
Filter bar (size S) with vertical filters

Components

Collapsed Filter Bar

The collapsed filter bar takes up very little space, leaving the bulk of the screen to display the actual results. However, the variant selector in the upper left corner is still available for switching between variants. The user can expand or collapse the filter bar by clicking the header. If required by the use case, the filter bar can be expanded by default.
On desktop and tablet devices, the collapsed filter bar shows a summary of the filters currently applied. It shows Filtered By (x):, where “x” stands for the number of applied filters. This is followed by a comma-separated list of the filters currently applied. Up to 5 filters are listed. If more filters have been applied, an ellipsis (…) shows at the end of the string. If no filters have been applied, the summary text is Not Filtered.
Collapsed filter bar
Collapsed filter bar

Expanded Filter Bar

Developer Hint
In addition to the collapsed filter bar, the expanded filter bar shows a user-defined filter subset of the currently selected variant.
The Adapt Filters (x) link opens the filter dialog, and allows the user to add filters or hide them. The Go button triggers the filter. The Go button is only shown in manual mode.
Expanded filter bar
Expanded filter bar

Filter Dialog

Developer Hint

The filter dialog is the central component that shows all filters of the selected variant, allowing the user to add filters to the variant or remove them. Filters are arranged into their respective filter groups. The user can search for a specific filter by name in the search bar at the top.

The footer toolbar at the bottom of the dialog provides the following functions:

  • Cancel: Closes the dialog and undoes all changes
  • OK: Executes the selected filter set

The header area of the filter dialog contains a Reset button. This resets the filter to the initial variant values (you can hide this button if it doesn’t fit the app use case). Before the filters are reset, the user gets a warning.

The user can choose to hide filters on the expanded filter bar by deselecting the relevant checkbox next to the filter in the filter dialog (for example, if a filter is rarely edited, or unimportant).

Information
In analytical list page scenarios, the warning for the reset button is not yet available.
Filter dialog
Filter dialog

Variant Selector

The variant selector is used to select the current variant, and also provides access to variant management.
Variant selector
Variant selector

Filter/Input Controls

Filter/input controls
Filter/input controls

When designing the filter bar, pick the simplest input control that works for your use case. Avoid unnecessary complexity in the filter bar.

If there is a predefined list for single or multiple selection, use the select control or combo box control. For temporal information, you can use the date picker or date range selector. To help the user enter a valid value for multi-input fields, you can enable suggestions.

For a comprehensive overview of when to use which input field, see Selection Controls – Overview.

Use the value help control only as a last resort. It is especially beneficial if you want to offer an advanced function for selecting single or multiple items either inline (by entering text) or by means of a dialog.

Developer Hint
For development information, see data types for the smart filter bar.

Behavior and Interaction

The filter bar contains the following actions:

Selecting a Variant

The main use case for the filter bar is to select and execute variants that influence the list of items. In this example, the variant applies its filter set automatically. The item list is filtered without the user needing to click Go.

Personalizing the Expanded Filter Bar

Users can hide a filter on the expanded filter bar by deselecting the checkbox next to the relevant filter in the filter dialog. This allows the user to hide filters that are rarely changed from the extended filter bar, giving complex filters a more lightweight appearance.

Saving a New Variant

You can save new filter variants in the variant selector.

Once you have changed an existing variant, an asterisk (*) is displayed next to the current variant name, indicating its “dirty state”.

You can either save the adapted variant with the current name (overwrite), or save it under a new name.

Variant Selector

Open the variant selector and choose Save As. Type your desired variant name into the input field and select OK.

Save new variant in variant selector
Save new variant in variant selector

Guidelines

Default Variant Filters

For all filter bars, provide a set of predefined default filters that come with the app (“Basic” group in the filter dialog). Include filters that are:
  • Mandatory / crucial to the use case
  • Frequently used
  • Vital for reducing the number of items in the list
Users can hide filters in the “Basic” group, but cannot remove them from the filter dialog.
Default variant
Default variant "Basic"

Default Values

Provide a meaningful default value for as many filters as possible. Meaningful default values depend on your use case.

A default value for date ranges, for example, should reflect the time frame the user would normally apply. App designers need to decide which time frame is appropriate.

Appropriate default values are particularly crucial for filter sets and list reports that operate on large datasets. In this case, consider making certain default filters mandatory to help the user avoid loading very large datasets unnecessarily.

For list reports and overview pages, ensure that mandatory filter fields always have default values. Otherwise, users will see error messages when the page loads.

Filter without default value
Filter without default value
Filter with available values
Filter with available values
Filter with a default value
Filter with a default value

Table Filtering and Table Searching

Provide the user with a central location filtering and searching. If you use a filter bar, do not provide filter options or search options for the control below (for example, a table, chart, or list.). Avoiding multiple filter locations also helps to prevent confusing or contradictory entries (for example between the filter bar and a table filter).
Do
Table without filtering option
Table without filtering option
Don't
Table with filtering option
Table with filtering option

Initial State

The filter bar can initially be collapsed or expanded, depending on the use case:

Initial State Collapsed

If the app has a default variant that is executed on loading, the table is prefilled, and the user seldom changes the filters, the app can start with a collapsed filter bar.

Initial State Expanded

If the app does not use a default variant and the user has to set a filter to obtain a first result set for the table, start with an expanded filter bar. Also, if a vast number of items are expected, include some mandatory filters with default values. Since the user first has to enter values for these filters, start with an expanded filter bar. If you are in any doubt, start the app with an expanded filter bar.

Note: At least one filter must be defined to begin with. This filter is set within the basic group by app designers. If the use case allows, and depending on the size of the result set, provide a table that is initially filled.

Initial state collapsed
Initial state collapsed
Initial state expanded
Initial state expanded

Basic Search Field

The basic search field allows the user to filter the results by a given keyword. In contrast to the other input fields, the basic search field has a placeholder text instead of a label.
Note: If you need to provide a search field, use the basic search field. The search field within the table must be deactivated.
Filter bar with basic search field
Filter bar with basic search field

Live Update / Manual Update

The filter bar is available in two separate modes: Live update mode and manual update mode.

Live Update

In the live update mode, the filter bar reacts instantly to every input change. The result table is updated every time the user changes a filter field or the search field. Therefore, a Go button is not necessary.

The search is triggered with every letter that is entered, starting with the first letter the user types. The table is updated with the results that match all set filters and include the search term.

Manual Update

In the manual update mode, the filter results are only updated when the user clicks Go. A Go button is therefore mandatory in manual update mode. Pressing ENTER on the keyboard also triggers the filter.

Which Mode Should I Use?

The live update mode is more convenient for the user. However, if the user has to configure multiple filters to obtain a useful result set, or if the resulting traffic is expected to be excessively high, consider using the manual update mode instead.

Filter bar in live update mode
Filter bar in live update mode
Filter bar in manual update mode
Filter bar in manual update mode

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

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
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 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 and minutes
Dropdown with hours, minutes, seconds, and AM/PM
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
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)
Set the time by swiping up and down (mobile)

Style

The Time Picker has five basic value states:

  1. Regular
  2. Information
  3. Success
  4. Warning
  5. Error

The information, warning, and error states can also have a message with additional information below.

Time picker value states
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

Implementation

Smart Field

The smart field creates different user input controls and their read-only equivalents based on an OData (Open Data Protocol) service and its annotations. It comes with additional built-in features, such as autocomplete and suggestions, value help dialogrecently used and recommended valuesvalidation, and message handling.

Information
The smart field is only available for OData version 2.

When to Use

Use the smart field if:

  • You use an OData service for your app (OData version 2 only).
  • The feature set of the smart field fits your app. In this case, the smart field is faster to implement.
  • You use the smart table and your app is not performance-critical. The smart field offers more flexibility than the controls provided directly by the smart table, especially for editing.
  • You use a smart form.

Do not use the smart field if:

  • You use a different technology to OData version 2. Use the corresponding controls directly.
  • You need a different control for entering or displaying data, such as multi input, a multi combo box, step input, a radio button, or a title. In this case, use the corresponding control directly.
  • You need a different dialog for offering value help, such as the select dialog or table select dialog.
  • You use the smart table and your app is performance-critical. In this case, the controls offered directly by the smart table offer less flexibility but better performance.

Components

The smart field consists of a basic UI element and an optional label. The following UI elements are available:

 For details, see the corresponding guideline topics. 

User Input Control

The smart field chooses the control automatically based on the data type (Edm type) and annotations of the OData service and additional properties. The following controls are used:

Read-Only Edit Edm Types / Annotations / Properties Comment
Single-line text Text Input field Edm.String

Configuration: controlType, value: input

Combo box Edm.String

Configuration: controlType, value: dropDownList

Select Edm.String

Configuration: controlType, value: selection

Multi-line text Text Text area Edm.String

MultiLineText

Decimal numbers Text

Object number

One or two input fields
(for number and unit)
Edm.Int16, Edm.Int32, Edm.Int64,
Edm.SByte, Edm.Byte,
Edm.Single, Edm.Float, Edm.Double,
Edm.Decimal
Precision, Scale
Status information Object status Edm.String

criticality, criticalityRepresentationType

Text and ID Text

Object identifier

Object status

Input field TextArrangement

controlProposal

displayBehavior

textInEditModeSource, sap:text,
fetchValueListReadOnly

The following patterns can be selected via displayBehavior:

  • Text (ID)
  • ID (Text)
  • Text
  • ID
Links
(with/without quick view)
Link

Smart link

Edm.String

IsURL, url

semanticObjectController

Dates Text Date picker Edm.DateTime

sap:display-format=”Date”

IsCalendarDate

Configuration: controlType

Dates and times Text Date/time picker Edm.DateTime

Edm.DateTimeOffset

Times Text Time picker Edm.Time
Fiscal periods Text Input field IsFiscalYear, IsFiscalPeriod,
IsFiscalYearPeriod,
IsFiscalQuarter, IsFiscalYearQuarter,
IsFiscalWeek, IsFiscalYearWeek,
IsDayOfFiscalYear
Amounts with currencies Text One or two input fields ISOCurrency or sap:unit with sap:semantics=”currency-code”
Phone numbers Text Input field IsPhoneNumber
Email Text Input field IsEmailAddress
Boolean Checkbox Checkbox Edm.Boolean
Text Combo box Edm.Boolean

valueList

displayBehavior

The text in display mode can be influenced via displayBehavior:

  • Yes/No
  • True/False
  • On/Off
Guidelines

  • Set a default value whenever appropriate (annotation: text, property: value).
  • To show a static unit of measurement, use a description (annotation: text).
  • To display a text and ID in the same place, use the format Text (ID) wherever possible. Use another format only if displaying the text doesn’t make any sense. Be careful when using the text arrangement options in tables: end users will only be able to sort, group, or filter based on the ID, even if the ID isn’t visible.
  • If you are not using the smart field within a smart form or smart table, label the smart field with a smart label (annotation: label, properties: textLabel, showLabel). The standard label doesn’t know the inner structure of a smart field.
  • You can set a tooltip (annotation: QuickInfo), but this should usually be avoided. See Using Tooltips.
  • If data entry is expected in a specific format, set a placeholder (property: Placeholder).

Developer Hint
Performance: Using the TextArrangement annotation to display both the text and ID (in any order) triggers two requests to the back end.

Behavior and Interaction

Context

You can use the smart field in different contexts
(property: controlContext):

  • Standalone
  • Within a form (depending on the form layout)
  • Within a table (depending on the table type)

The context influences:

  • Labels: In most cases, forms provide the label automatically.
  • Empty values in display mode: In forms, empty values are shown as a dash. In tables, the field remains blank.
  • How units of measurement are displayed
Guidelines

  • If the width is not handled by the context, set a meaningful width for the smart field, based on the expected data (property: Width).
  • If you use a “standalone” smart field  in a form-like arrangement, use a dash to show an empty value in display mode.

Switching Between Edit and Display Mode

Switching between edit and display mode can be controlled manually (annotation: FieldControl, property: editable) or automatically by the containing smart form or smart table (property: contextEditable).

Smart field as a select with 'required' indicator in edit mode
Smart field as a select with 'required' indicator in edit mode
The same smart field in display mode
The same smart field in display mode
Guidelines

  • Define which fields should be editable (annotations: updateable, creatable, updateable-path, InsertRestrictions, UpdateRestrictions, computed, immutable, fieldControl, fieldControlType).
  • For fields with a unit of measurement, define whether the unit of measurement is editable or static (annotation: FieldControl, property: uomEditable).
  • Make sure that the full text is shown in display mode (property: wrapping), unless this is handled differently for the corresponding context (for example, see guidelines for content in the grid table).
  • When you display the text and ID, the smart field automatically displays both values in display mode, but only the ID in edit mode (annotation: TextArrangement). In most cases, it makes sense to also display both values in edit mode (annotation: sap:text, property: textInEditModeSource, aggregation: Configuration with property: displayBehavior).

Suggestions and Value Help

You can enable suggestions for controls that offer this feature (property: showSuggestions). The list of suggestible values must be provided (annotation: ValueList or ValueListWithFixedValues only for Edm.String, property: entitySet). This list can contain several attributes and is also used for the value help dialog. You can restrict the number of attributes from this list to be shown as suggestions, while all attributes are shown within the value help dialog.

Autocomplete is enabled automatically.

For input fields, the value help dialog is also created automatically. Hide it if it is not needed (property: showValueHelp). The table in the value help dialog can be filled with initial content (annotation: ValueList, property: fetchValues, sap.ui.comp.smartfield.Configuration, property: preventInitialDataFetchInValueHelpDialog)

Both the value help dialog and the suggestion list can be prefiltered (annotation: ValueList, property: valueListParameterIn). The selected items can be used to prefilter other fields (annotation: ValueList, property: ValueListParameterOut). The corresponding filter settings are visible. “Invisible” prefiltering is also supported. To use this option, provide the exact matching filter value (Common.ValueListParameterConstant).

If a value has been entered in the smart field, this value is transferred to the search field of the value help dialog automatically. In the value help dialog, individual values can be valid, deprecated, or revoked. Revoked values are hidden from the value help (annotation: IsConfigurationDeprecationCode).

The following controls are used to offer suggestions or value help:

Smart field as a combo box
Smart field as a combo box
Smart field as an input field with suggestions, auto complete and a value help button
Smart field as an input field with suggestions, auto complete and a value help button
The automatically generated value help dialog for the same smart field
The automatically generated value help dialog for the same smart field

Recently Used Values

Input fields, combo boxes, and selects can provide up to five recently used values automatically on focus if suggestions or value help are available. This can be turned on or off per field (property: historyEnabled). Recently used values are shown by default for input fields, but not for combo boxes and selects.

Guidelines
Do not show recently used values for a field if:

  • There are only a small number of options.
  • The field contains personal sensitive data (annotation: IsPotentiallySensitive).
  • It is unlikely that the same values will be selected again and again.

Recommended Values

In addition to recently used values, a smart field can show recommended values (annotation: RecommendationState).

The corresponding smart field is highlighted and/or prefilled:

  • If no recommendation is available or the current user input matches the recommendation, the smart field is shown in the default state.
  • If a recommendation is available and there is no user input, the smart field is shown in the information state.
  • If a recommendation is available and it differs from the current user input, the smart field is displayed in the warning state.

The recommended values are shown as soon as the user focuses on the smart field.

Validation

The smart field offers the following validations automatically:

  • Validation for required fields: This can be done on the client or server side (property: clientSideMandatoryCheck, annotation: Nullable).
  • Validation for a group of fields: Validation is triggered when the focus moves outside a group of fields, rather than when a single field loses the focus. A group is defined by all smart fields that share the same field group ID (property: fieldGroupIds).
  • Validation for the maximum length of user input: Validation is triggered when a field loses the focus or the ENTER key is pressed (property: maxLength).

The validation result is indicated by a value state (property: showValueStateMessage).

When the user edits a smart field showing a text and ID, you can allow any kind of input to avoid unnecessary validation issues (annotation: ValueListNoValidation).

Examples:

  • Allowing the user to enter additional values (which are not in the suggestion list)
  • Typing a text instead of an ID to filter down the suggestion list
  • Using the smart field in a draft
Automatic validation
Automatic validation

IDs

The smart field offers automatic validation for number-only ID fields (annotations: IsDigitSequence or sap:display-format="NonNegative"):

  • It checks for non-negative numbers.
  • It shows values containing only “0” digits as empty.
  • It does not show leading zeros.

Units

For decimal number fields and for fields that show an amount with a currency, you can add a unit of measure  (annotations: unit, sap-unit with sap:semantics="unit-of-measure" or sap:semantics="currency-code", property: uomVisible). In display mode, the unit is added to the corresponding number. In edit mode, the unit is shown either as text or, if editable, as a second input field (properties: uomEditable, uomEnabled).

Smart field showing an amount with a currency in display mode
Smart field showing an amount with a currency in display mode
The same smart field in display mode
The same smart field in display mode

Sensitive Data

Sensitive data, such as passwords, can be masked. The text is then replaced with asterisks (annotations: IsPotentiallySensitive, masked).

Capitalizing Text Input

Text input can be capitalized automatically (property: IsUpperCase).

States

Smart fields support the following states (annotation: fieldControl):

  • Editable or display only (additional annotations: updateable, creatable, updatable-path, InsertRestrictions, UpdateRestrictions, property: editable)
  • Enabled or disabled
  • Visible or hidden (additional annotations: property: visible, annotation: sap:visible)
  • Required: If set, the smart field must contain a value when validated. This is indicated by an asterisk next to the corresponding label (additional annotation: Nullable, property: mandatory).

The following states for a unit of measurement can be set independently of the corresponding field:

  • If editable, a unit of measurement can be enabled or disabled (property: uomEnabled)
  • The unit of measurement can be visible or hidden (property: uomVisible)
Developer Hint
In the SAPUI5 SDK API Reference for the smart field, the display only state is referred to as read only.

Dependencies between Smart Fields

If the content of a smart field is changed, you can trigger additional changes to other fields on the UI (annotation: SideEffects).

Content Alignment

You can change the horizontal alignment of the text within any kind of input field  (property: textAlign).

Guidelines
Follow the alignment rules for the respective context (responsive table, other tables, form). If you are using the standalone option for the smart field (without a context), apply the rules for the corresponding input fields.

Responsiveness

The smart field acts exactly like the embedded controls. For details see:

Top Tips

  • Always label a smart field if it is not inside a table context.
  • Use suggestions with autocomplete whenever possible and meaningful.
    • Do not show suggestions if there are only a few choices.
    • Use recently used values as appropriate.
    • Reduce the number of attributes shown in the suggestion list to a maximum of 4 or 5.
  • Make use of validation features.

Properties

The following properties, aggregations, and associations are available for sap.ui.comp.smartfield.SmartField:

  • The property: expandNavigationProperties is experimental. Do not use it.
  • The property: jsontype is deprecated. Do not use it.
  • The property: name is used in HTML forms that send data to the server via “Submit”.
  • The property: uomEditState is for internal use only. Do not use it.
  • The property: proposedControl is deprecated. Do not use it.
  • The property: textDirection provides support for reading directions in different locales.
  • The aggregation: controlProposal is deprecated. Do not use it.
  • The association: ariaLabelledBy can be used for linking additional labels to the smart field.

Related Links

Elements and Controls

Implementation

Value Help Dialog

Intro

The value help dialog is a UI pattern that helps the user find and select single and multiple values. The user can also define and select multiple conditions. The value help dialog is generally called from an input field or a multi-input field by clicking the selection icon (value help icon) of the input field.

Usage

Use the value help dialog if:

  • The user is searching within a dataset that contains more than 1,000 items.
  • The user needs to use different attributes to find an object (such as city, company name, and so on).
  • The user needs to define conditions, such as ranges and exclusions.

Do not use the value help dialog if:

  • There is a simpler control that fits the use case. Always start with the least complex control. For example, use the select control if the user needs to select only one item from a short list.
Information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

The behavior of the value help dialog on a phone differs from its behavior on a tablet or desktop device. Both the navigation and the positioning of the selection area differ depending on the device.

Value help dialog - Size S
Value help dialog - Size S
Value help dialog - Size M
Value help dialog - Size M
Value help dialog - Size L
Value help dialog - Size L

Components

The value help dialog contains the following components:

1) Header
2) Icon tab bar / list control (phone)
3) Search template (optional)
4) Basic search
5) Go button
6) Filters
7) Result list
8) Selected items and conditions
9) Footer toolbar
10) Area for defining conditions, such as ranges and exclusions

Header (1)

The header bar contains the dialog title. See the Guidelines section below.

Icon Tab Bar / List Control (Phone) (2)

Depending on the device, the following controls are used to display the content of the value help dialog:

  • Smartphones: The start dialog provides a list (sap.m.List) with the standard list items (sap.m.StandardListItem), Search and Select, and Define Conditions to navigate between the different dialogs.
  • Tablet and desktop devices: The value help dialog contains an icon tab bar (sap.m.IconTabBar) to navigate between the Search and Select and the Define Conditions tab.
  • Both controls have a counter in the title that indicates the number of items/conditions selected.

Search Template (3)

Search templates allow the user to display different or additional fields in the filter area and result list. Depending on the use case, the user can switch between the different search templates in order to use different fields when searching. For example, the search template “Customer (by Company Code)” displays the additional field “Company Code” in the filter area and result list.

Basic Search (4)

The basic search finds all results that are somehow related to the input. For example, the search term “A” returns all the results containing the letter “A”.

Always offer the basic search in the value help dialog. Position the basic search to the right of the search template control. If there is no search template control, left-align the basic search.

Go Button (5)

The Go button triggers the search and filters the result list.

Filters (6)

The filter area offers a filter field for each column in the result list. In some cases, there can be specific filter fields that do not have a corresponding column on the UI. These fields typically come from the back-end service.

Value help dialog - Filters
Value help dialog - Filters

For the basic search with filters, the filter bar (sap.ui.comp.filterbar.FilterBar) is implemented in advanced mode. Advanced mode differs from basic mode in the following ways:

  • There is no Filters link or a dialog to make additional filter fields visible. All filter fields fields are added automatically to the filter area.
  • There is a toggle button to show and hide the filters.
  • In each of the filter fields, users can use operators like “between” or “lower than” to define conditions.

Always hide the filter area in the value help dialog by default. Only show the filter area by default if the basic search can’t be provided.

Note that the value help icon of the Product ID field in the current value help dialog will open only the Define Conditions screen. The full value help dialog is not shown in order to prevent endless loops. For example, the value help icon of the Product Name or Category field in the value help for a Product field will navigate directly to the Define Conditions: Product screen.

Using the Filters

Users can enter operators (such as “=“) to define the conditions directly within the field without opening the Define Conditions tab.

Users must use the following notation to get results:

Operator Input Notation Example
between valuevalue 000100
equal to =value =0001
contains *value* *1*
starts with value* 001*
ends with *value *5
less than <value <100
less than or equal to <=value <=200
greater than >value >0300
greater than or equal to >=value >=0500
not between !(valuevalue) !(000100)
not equal to !(=value)  !(=0)
does not contain !(*value*)  !(*1*)
does not start with !(value*)  !(001*)
does not end with !(*value)  !(*5)
not less than !(<value) !(<100)
not less than or equal to !(<=value) !(<=200)
not greater than !(>value)  !(>0300)
not greater than or equal to !(>=value)  !(>=0500)
empty <empty>   <empty>
not empty !(<empty>)    !(<empty>)
Using an operator to filter the result list
Using an operator to filter the result list

Result List (7)

  • The result list is populated on initial load by default.
  • If you transferred values from the input field to the basic search field of the value help dialog, the results are filtered accordingly. Only the entered (or modified) value is transferred to the basic search. Type-ahead suggestions are ignored. The search is triggered automatically when the dialog opens.
  • If available, display the ID and description of the business object in the first and second columns. Display additional information in the next columns.
  • We recommend a maximum of five columns in the result list.

Selected Items and Conditions (8)

The selected items and conditions are displayed in a tokenizer (see token for more information). Each selected item or condition is displayed as one token.

There is no longer a visual difference between included and excluded items and conditions. They are now differentiated using operators (see Using the filters).

Footer Toolbar (9)

The footer bar offers the OK and Cancel buttons.

Area for Defining Conditions (10)

In the Define Conditions tab, you can use the following operators to define single and multiple conditions:

  • between
  • equal to
  • contains
  • starts with
  • ends with
  • less than
  • less than or equal to
  • greater than
  • greater than or equal to
  • empty
  • not between
  • not equal to
  • does not contains
  • does not start with
  • does not end with
  • not less than
  • not less than or equal to
  • not greater than
  • not greater than or equal to
  • not empty

For convenience, the operators are grouped into two categories: Include and Exclude.

Each condition is displayed as a token in the Selected Items and Conditions tokenizer.

Information
The operator dropdown list may not contain all the operators listed above. The type of field value determines which operators are available.
Developer Hint
For information on how to manage white space characters (blanks) when users copy and paste text into input controls, see Removing Leading and Trailing White Space.
Define Conditions - Operators List
Define Conditions - Operators List

Behavior and Interaction

Basic Search and Filters

  • The basic search (mandatory) and filters (optional) are triggered by clicking the Go button. The search results are shown in the result list.
  • If data was already entered in input field from which the user triggered the value help, this data is transferred to the basic search and the results are then filtered accordingly.
  • The basic search performs a search across all fields that are displayed in the filter area and the result list.

Selecting Items and Defining Conditions

Depending on your use case, the value help dialog can offer different selection options:

  • Select a single item
  • Define a single condition
  • Select multiple items
  • Define multiple conditions
  • Select multiple items and define multiple conditions

Users open the value help dialog by clicking the value help icon in the input field. The next steps depend on the use case and form factor (smartphone or desktop/tablet).

The different use cases are described in the sections below.

Select a Single Item (Smartphone)

Tapping the value help icon opens the dialog. As soon as an item is selected, the value help dialog closes automatically.

Single item selection on a smartphone
Single item selection on a smartphone

Select a Single Item (Desktop/Tablet)

Clicking the value help icon opens the value help dialog for single selection. The icon tab bar and the Selected Items and Conditions are hidden. As soon as an item is selected, the value help dialog closes automatically.

Single item selection on a desktop/tablet device
Single item selection on a desktop/tablet device

Define a Single Condition (Smartphone)

Tapping the value help icon opens the Define Condition tab. Users define a condition by choosing the relevant operator and entering the value or values in the corresponding input field(s).

In this example, we have defined a range.

Defining a single condition on a smartphone
Defining a single condition on a smartphone

Define a Single Condition (Desktop/Tablet)

Clicking the value help icon opens the Define Condition tab. Users define a condition by choosing the relevant operator and entering the value or values in the corresponding input field(s).

In this example, we have defined a range.

Defining a single condition (desktop/tablet)
Defining a single condition (desktop/tablet)

Select Multiple Items and Define Multiple Conditions (Smartphone)

Tapping the value help icon displays the start dialog.

  • The Search and Select tab is used to select multiple items.
  • The Define Conditions tab is used to define multiple conditions.
  • The counters in the titles of both tabs represent the number of selected items/defined conditions.

All selected items and conditions are added as tokens to the Selected (n) field at the bottom of the start dialog. The counter n indicates the combined number of items selected and conditions defined.

Start dialog
Start dialog
Selecting multiple items on a smartphone
Selecting multiple items on a smartphone
Defining multiple conditions (smartphone)
Defining multiple conditions (smartphone)
Filters on a smartphone
Filters on a smartphone

Select Multiple Items and Define Multiple Conditions (Desktop/Tablet)

Clicking the value help icon displays the icon tab bar with the Search and Select and Define Conditions tabs.

  • The Search and Select tab is used to select multiple items
  • The Define Conditions tab is used to define multiple conditions.

All selected items and conditions are added as tokens to the Selected Items and Conditions (n) field at the bottom of the dialog. The counter n indicates the combined number of items selected and conditions defined.

Selecting multiple items and conditions on a desktop
Selecting multiple items and conditions on a desktop
Selecting multiple items and conditions on a desktop
Selecting multiple items and conditions on a desktop

Define Multiple Conditions (Smartphone)

Tapping the value help icon opens the start dialog with the Define Conditions tab.

The selected values are added as tokens to the Selected Conditions at the bottom of the start dialog.

Start dialog
Start dialog
Defining multiple conditions on a smartphone
Defining multiple conditions on a smartphone

Define Multiple Conditions (Desktop/Tablet)

Clicking the value help icon opens the Define Conditions tab.

The selected values are added as tokens to the Selected Conditions at the bottom of the start dialog.

Defining multiple conditions on a desktop
Defining multiple conditions on a desktop

Copying and Pasting Multiple Values

The area for defining conditions allows the user to enter multiple values at once (copied from the clipboard).

Users can paste more than one value into the value input field. In this case, the condition row repeats with the previously selected condition and shows one value per row.

If there are more than 10 rows of conditions, pagination is added to top of the respective area.

Copying and pasting multiple values
Copying and pasting multiple values

Guidelines

Dialog Title

The dialog title differs depending on the device and whether multiple or single selection is used.

For smartphones:

  • Start dialog: [Object] (for example, Company)
  • Search and Select Dialog: Search and Select
  • Filters dialog: Show Filters
  • Define single condition: Define Condition
  • Define multiple conditions: Define Conditions

For tablet and desktop devices:

  • Selection of multiple items combined with selection of multiple conditions: [Object] (for example, Company)
  • Single item selection: Select: [Object] (for example, Select: Company)
  • Define single condition: Define Condition: [Object] (for example, Define Condition: Company)
  • Define multiple conditions: Define Conditions: [Object] (for example, Define Conditions: Company)

Filtering

If necessary, also provide value help for fields offered in the filters. However, do not provide the full value help dialog for the ID and description fields of the business object that is being selected. For these two fields, make sure that the value help icon opens only the Define Conditions screen.

For example, in a value help dialog for selecting the customer, do not offer full value help for the Customer ID and Customer Name fields. Instead, try to use the value help in combination with a helpful suggestion.

Related Links

Elements and Controls

Implementation

Rating Indicator

The rating indicator can be used to rate content or to indicate a rating. It enables users to rate an item on a numeric scale. The most popular scale is 1 (lowest) to 5 (highest).

Rating indicator
Rating indicator

Responsiveness

The rating indicator runs on all form factors and therefore works on all devices. It is embedded in a container and thus behaves as part of it.

Rating indicator as part of a form – Size S
Rating indicator as part of a form – Size S
Rating indicator as part of a form – Size M
Rating indicator as part of a form – Size M

Layout

Context

You can use the rating indicator in forms, tables, in a dialog box, or in the filter bar.

Rating indicator as part of a form
Rating indicator as part of a form
Rating indicator in the filter bar / as part of a table
Rating indicator in the filter bar / as part of a table
Rating indicator as part of a dialog
Rating indicator as part of a dialog

Popover with Details

In collaborative rating scenarios, the rating indicator shows an average of all ratings. You may show the sum of ratings in brackets behind the rating indicator as a text or link. You may also add a popover that shows the detailed ratings for the average of all ratings.

Rating details in a popover
Rating details in a popover

Behavior and Interaction

Hover

When the user hovers over the rating indicator, a different icon or image is shown (property: iconHovered). This is an orange star by default.

Select

If enabled for rating, the rating that the user previously selected is shown. When the user performs a rating, an event is triggered.

Types

There are two types of rating indicators:

  • Interactive – used for rating an item
  • Disabled

As the non-interactive state (rating result preview) is not available currently, use the disabled state instead.

Interactive state
Interactive state
Non-interactive state
Non-interactive state
Display mode
Display mode
Disabled
Disabled

Properties

Rating Symbols

You can also specify the URLs for the images or icons that are used as rating symbols (property: iconUnselected). Five star symbols are used by default. Although you can use other images or icons, we generally recommend that you use the star symbol. You can only choose 1 symbol for the unselected and 1 for the hovered state.

Number of Rating Symbols

You can specify the number of rating symbols (property: maxValue). We recommend using a maximum of 7 symbols, although 5 symbols are preferred.

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
Possible sizes of a rating indicator: L, M, S, and XS

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Mask Input

The mask input control (sap.m.MaskInput) governs what a user is permitted to enter in an input field. It allows users to easily enter data in a certain format and in a fixed-width input (such as a date, time, phone number, credit card number, currency, and IP address).

Usage

Use mask input if:

  • You have to govern what a user is allowed to enter in an input field.
  • You have to enter data easily in a certain format and in a fixed-width input.
  • You have to enter input such as a date, time, phone number,  serial number, ISBN, or product activation key.

Do not use mask input if:

  • The mask prevents users from entering essential data.
  • The users need to enter data in a format other than the one used by the mask (for example, if users have to enter a phone number with a format for a different region).

Responsiveness

Mask input extends the input control (sap.m.Input) and has all the normal properties of an input field.

Components

The mask input control has a fixed length format to which the user’s input must conform. This can be particularly useful when the user needs to enter text or numbers with specific formatting, such as a phone number, postal code, or credit card number.

Mask input or a placeholder text are not substitutes for the input label. Using a label is mandatory. Placeholder texts in an input field are optional. Note that if there is no placeholder text, the input field will initially look empty. The mask formatting is revealed as soon as the focus is on the field.

Mask input without placeholder text
Mask input without placeholder text
Mask input with placeholder text
Mask input with placeholder text

Immutable Characters

When defining the mask format, the developer can place immutable characters, such as brackets and dashes, in specific positions. The format also specifies the range of valid characters for each separate position, thus preventing the user from entering invalid input.

For example, when the user enters a phone number, the area code in brackets and the space between the numbers are already present.

Note that the sap.m.MaskInput control extends sap.m.Input and has all the normal properties of an input field.

When creating a new mask, the developer can change the configuration of some default properties. For example, the default placeholder symbol “_” can be changed to something else.

Behavior and Interaction (incl. Gestures)

Entering Text

  • Mask string appears in the input field on focus.
  • The default placeholder symbol is “_” and can be changed to something else.
Entering text into a mask input
Entering text into a mask input

Copying and Pasting

Copying to a mask input field:

Users can copy both formatted and unformatted strings into a mask input field. When the texts are pasted, they take on the format defined for the mask input field.

Example: Mask input field for a number with the format:  (000) 000 000000

Copied source string Value in mask input field after pasting
(555) 333 123456 (555) 333 123456
555-333-123456 (555) 333 123456
555 (333) 12 34 56 (555) 333 123456

Copying from a mask input field:

If you copy a string from a mask input field and paste it elsewhere, the format of the mask input field is copied as well.

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.

Deleting Content

Deleting a character from the string leaves the input information unchanged, except for the deleted character, which is replaced by a placeholder. (The mask does not shift if a character is deleted.)

Deleting individual characters in mask input
Deleting individual characters in mask input

Select the entire string and delete it. The placeholders will reappear.

Deleting all characters in mask input
Deleting all characters in mask input

Guidelines

Validation Rules

Another option is to define new validation rules, such as allowing lowercase characters from “a” to “e” only. This is particularly flexible because these rules are defined with regular expression syntax.

The mask comes with two predefined validation rules: one for all characters in the English alphabet, and one for the numbers from zero to ten.

Therefore, when the mask format is being defined, the alphabetic rule is represented by the letter “a”, and the numeric rule by the number “9”. For example, a numeric mask format with a length of five characters would be specified as “99999”, a mask that accepts only alphabetical characters would be specified as “aaaaa”, and a mixed mask could be “aaa99”. In the mixed mask example, the user would not be able to enter numeric characters anywhere other than in the last two positions.

When you create the MaskInput instance, you can specify the following settings:

  • Mask: The format specification, such as (123) 999-999.
  • PlaceholderSymbol: A single character used to represent empty positions in a mask value, such as _ _ _ _ _.
  • Rules: A collection of sap.m.MaskInputRule instances.

Unit of Measurement

You can use the layout options of the form to can add the unit of measurement (UoM) after the mask 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.

Properties

Mask string

The mask is defined by its character type (or by its length, as applicable). You should consider the following important facts:

  1. The mask characters normally correspond to an existing rule (one rule per unique character). Characters that do not are considered immutable characters. For example, the mask ‘2099’, where ‘9’ corresponds to a rule for digits, has ‘2’ and ‘0’ as immutable characters.
  2. Adding a rule that corresponds to the symbol placeholder is not recommended and would lead to unpredictable behavior.

Placeholder symbol string  “_”

This defines a placeholder symbol. It is shown in a position where there has not yet been any user input.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

P13n Dialog

Intro

The p13n dialog control provides a dialog for tables that allows the user to personalize one or more of the following attributes:

  • Columns (visibility and order of columns)
  • Sort (sorting of table values)
  • Filter (filtering of table values)
  • Group (grouping for specific attributes)

These tabs can be shown in any combination, as the use case requires.

The P13n dialog is intended for complex tables with a large number of columns and the need for complex queries for sorting, grouping, and filtering.
For simple tables, see view settings dialog and table personalization dialog.

The P13n dialog can be triggered in the table toolbar using the corresponding buttons in the top right-hand corner of the table.

The dialog is shown centered, either as a dialog (on desktop and tablet devices) or as a full-screen dialog (on mobile devices).

Dialog buttons within the table toolbar
Dialog buttons within the table toolbar

Usage

Use the P13n dialog if:

  • The user is able to personalize more than 20 or so columns.
  • You need several functions for sorting, grouping, and so on.
  • You are using the analytical table.
  • Complex queries have to be built for the relevant table.

Do not use the P13n dialog if:

  • The user is able to personalize fewer than about 20 columns.
  • You only need a simple column show/hide feature.

Responsiveness

The P13n dialog is available for all display sizes. For sizes L/XL (desktop) and M (tablet), the dialog is shown as a dialog. For size S (smartphones), the P13n dialog is displayed as a full-screen dialog.

Size S – Columns
Size S – Columns
Size M
Size M
Size L
Size L

Components

The P13n dialog consists of four different tabs that can be used separately or combined, as required by the use case:

  • Sort
  • Filter
  • Group
  • Columns

App developers can add more tabs manually.

Behavior and Interaction

Columns

The first tab is the Columns tab. It allows the user to change the table columns that are shown and the order in which they are displayed.

The list contains all of the table’s possible columns in the form of list items with checkboxes. The checkboxes of the currently displayed columns are selected.

Another button next to the search field in the table toolbar allows the user to toggle between showing all columns and only those that are currently selected in the list.

Show/Hide

To show or hide a column, select or deselect the appropriate checkbox.

Reorder

To change the order of the columns, simply mark one list item and use the buttons on the right-hand side of the table toolbar to move them up or down. The order of the columns from top to bottom corresponds to the order on the table from left to right.

Search

If the table has numerous columns, the user can use the search field in the table toolbar to find a specific column more quickly. As soon as the user enters the first letter, the resulting columns are displayed instantly.

Column settings in the P13n dialog
Column settings in the P13n dialog

Sort

The second tab is the Sort tab, which allows the user to sort the table content according to the chosen attributes, and also in either ascending or descending order.

The sort criterion consists of two input fields. In the first field, the user can choose a column by which the table is to be sorted. In the second field, the user chooses the sort order (ascending or descending).

For more complex sorting needs, the user can add the required number of criteria by clicking the plus “ ” sign at the end of the line.

The order of the criteria is exactly the same as the order in which sorting is applied to the table.

Sort settings in the P13n dialog
Sort settings in the P13n dialog
Information
Using the sort feature on column headers replaces ALL sort options in the dialog!

Filter

The third tab is the Filter tab, which allows the user to filter the table information according to specific criteria.

The filter criteria can be included or excluded in the relevant section of the filter.

Column

In the first input field, the user selects the column to be filtered. Any of the columns can be selected; even those that are not currently visible.

Option

The second field offers an operator for specifying the filter in more detail. The operators that are available depends on the data type of the selected column.

Filter tab in the P13n dialog
Filter tab in the P13n dialog

String (Text)

  • between
  • contains
  • equal to
  • begins with
  • ends with
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Number

  • between
  • equal to
  • greater than
  • greater than or equal to
  • less than
  • less than or equal to

Date

  • between
  • equal to
  • after
  • on or after
  • before
  • before or on

Boolean (true / false)

  • equal to

The only available operator for excluding values from the filter results is equal to.

Value

The last field contains the value by which the selected column is filtered. The kind of input field that is provided depends on the data type of the selected column.

Two or even more fields can be provided as required by the use case.

For more complex cases, the user can add filters by clicking the plus “ ” button or remove them by clicking the Remove button at the end of each filter item.

Information
If there is a filter bar, use its filter functionality and deactivate the filter feature of the P13n dialog.

Group

The last tab is the Group tab, which enables the user to group the table data by one or more columns.

In the first selection field, all columns are provided for selection. The user can select a checkbox on the right of the column selection field if the selected field is to be displayed as a column anyway.

For more complex grouping scenarios, the user can add more grouping options by clicking the plus “ ” button on the right-hand side of each grouping line. This option only works with the analytical table.

The grouped table shows the selected field as the group header, which can be expanded or collapsed.

Under the group headers, all subgroup headers and all applicable table entries are displayed.

Group tab in the P13n dialog
Group tab in the P13n dialog
Information
To group by a specific column, that particular column must be marked as visible on the Columns tab!

Guidelines

For opening the dialog from a table toolbar, use different buttons for each function (sort, filter, group, column settings). With each button, open the P13n dialog with just the corresponding tab. Do not display the other tabs.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Step Input

The step input control allows the user to change the input values in predefined increments (steps).

Usage

Use the step input if:

  • The user needs to adjust amounts, quantities, or other values quickly.
  • The user needs to adjust values for a specific step (for example, in a shopping cart).

Do not use the step input if:

  • The user needs to enter a static number (for example, postal code, phone number, or ID). In this case, use the regular input field control instead.
  • You want to display a value that rarely needs to be adjusted and does not pertain to a particular step. In this case, use the regular input field control instead.
  • You want the user to enter dates and times. In this case, use the date pickerdate range selectiontime picker, or date/time picker instead.

Responsiveness

Size S and M (Smartphone and Tablet)

On smartphones and tablets, the step input is shown in cozy mode. When the focus is in the input field, the keyboard layout for numeric input is displayed.

Size L (Desktop)

On desktop devices, the step input is shown in compact mode.

For more information on the cozy and compact modes, see content density.

Step input - size S/M
Step input - size S/M
Step input - size L
Step input - size L

Components

The step input consists of:

(A) Input field
(B) Button to decrease the value
(C) Button to increase the value

Step input areas
Step input areas

You can show a descriptive reference or unit of measurement after the field (property: description). Depending on your use case, you may need to adjust how the space is distributed between the input field and the descriptive text (property: fieldWidth).

Step input with description
Step input with description

Behavior and Interaction

Default Value

The step input always contains a value. When no value is set, the default value is generally 0. However, app developers can set a different default value (property: value).

If the minimum value is larger than 0, the generic value is the minimum value set by the app team.

Changing the Value

The user changes the value:

  • By pressing the increase/decrease buttons
  • By typing a number
  • With keyboard shortcuts (up/down, page up/down)
  • With the mouse scroll wheel

On desktop devices, clicking the input field places the cursor in the input field. On mobile devices, tapping the input field displays the numeric keyboard.

Clicking the buttons changes the value by a step and does not place the caret in the input field.

When the user clears the value and leaves the input field, the value in the field becomes 0 or the minimum if the minimum is larger than 0.

If the user enters an invalid value, the invalid value remains in the input field. An error state is displayed.

Increasing the Step

To allow the user to change values by a larger step with keyboard shortcuts, app developers can set a multiple of the step (property: largerStep). The default value is two times the set step.

If your use case requires more complex step increments (for example, if you want the step increment to be the closest number that is divisible by the defined step) you can use the stepMode property. For details, please refer to the API reference.

Maximum and Minimum Values

App developers can set a maximum and minimum value for the step input.

When the maximum/minimum values are reached, the Increase/Decrease button and up/down keyboard navigation are disabled.

Display Value

The step input control allows decimal values and can control the number of digits shown after the decimal point (property: displayValuePrecision). When the property is set to a specific value – from 0 (default) to 20 – the control restricts users accordingly as they type or paste a value. Trying to type more digits triggers an error state.

Step input at maximum value (max = 100)
Step input at maximum value (max = 100)
Step input at minimum value (min = -100)
Step input at minimum value (min = -100)

Styles

The step input control has different styles for its value states: error, warning, success, neutral, and information.

Error state
Error state
Warning state
Warning state
Success state
Success state
Neutral state
Neutral state
Information state
Information state

Guidelines

Always provide a meaningful label for the step input.

Width

By default the width of the step input is set to 100% of the container. Avoid setting a fixed width, but rather embed the control in a proper layout such as a form, simple form, or grid layout, and use the layout data property where the width is defined by the 12-column approach to define the responsive behavior for sizes S, M, and L.

When used in forms, the width of the step input control comes from the label:field ratio of the form. The app development team should be able to restrict the width to a proper number of columns (12-grid responsive layout) so that the step input is not too wide.

Ensure an appropriate width for the range of values to be entered for all the sizes S, M, and L. Avoid a larger width than necessary.

Keep in mind the varying lengths of decimals. Limit the number of digits after the floating point if possible in your use case. For more information, have a look at the article on formatting numbers.

Properties

Value States

The step input control offers the five value states listed below. For the error, warning, and information states, you can show an additional value state text when the focus is on the input field.

  • Warning
  • Error
  • Success: No value state message is shown
  • Neutral (default): No value state message is shown
  • Information: Value state message can show additional information, such as recommendations.

For more information on how to use the different semantic states, see How to Use Semantic Colors.

For more information on showing value states in a form, see Form Field Validation.

Error state – With value state text
Error state – With value state text
Warning state – With value state text
Warning state – With value state text
Success state – No value state text
Success state – No value state text
Neutral state – No value state text
Neutral state – No value state text
Information state – With value state text
Information state – With value state text

Editable and Enabled States

Editable

Property settings: editable = true, enabled = true

The step 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.

Read-only state
Read-only state
Disabled state
Disabled state

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Rich Text Editor

The rich text editor (RTE) is a complex control for data input and editing. It allows users to format the text and insert different types of elements within the text, such as images and hyperlinks.

The rich text editor uses the third party component TinyMCE. In addition to the native toolbar, you can also use a toolbar built with SAPUI5 controls. This custom toolbar acts as a wrapper around the native toolbar and takes care of synchronizing the state of the internal controls with the current state of the selection in the editor.

Rich text editor
Rich text editor

Usage

Use the rich text editor if:

  • You want to enable users to enter rich text with different styles and colors.
  • You need to provide an instrument for texts that require additional formatting.

Do not use the rich text editor if:

  • You want to let users add simple text that doesn’t require formatting. Use text area instead.

Responsiveness

The rich text editor is intended primarily for use on desktop devices, even though it still displays smoothly on mobile devices. You can also enable the mobile theme of TinyMCE, but we don’t recommend using it as it comes with some limitations explained in the Mobile Theme section.

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 in the toolbar, the extra actions disappear from the visible part of the toolbar from right to left, and an overflow menu button appears on the right of the toolbar. Clicking the overflow button reveals the hidden options.

Each action has a priority, which determines whether and when the action moves into the overflow menu. You can prioritize the actions in the toolbar by applying one of five statuses:

  • Always overflow: The action always goes into the overflow.
  • Disappear: An action that is not so relevant for the user can disappear if the space is limited.
  • Low: Actions with the priority “Low” overflow first. Assign this status to actions the user rarely needs.
  • High: Actions with priority “High” remain visible in the toolbar until all lower-priority actions have moved to the overflow. Lower-priority actions are those with the priorities “Disappear” or “Low”, and all unprioritized actions.
  • Never overflow: These actions are always visible in the toolbar.
Size S
Size S

Mobile Theme

From version 4.7, TinyMCE provides native mobile support with the mobile theme. If your use case requires it and you have enabled the mobile theme, the custom toolbar cannot be used, and the native TinyMCE toolbar and layout are loaded. This is why we don’t recommend using the mobile theme.

Layout

The rich text editor has two main components – the toolbar and the content area.

  • Toolbar: All available actions are displayed in the toolbar. App development teams can add or remove individual action groups, depending on the use case.
  • Content area: The content area is where users create their text. It visualizes all the changes made using the actions in the toolbar.
Schematic visualization of the rich text editor
Schematic visualization of the rich text editor

Toolbar Types

The rich text editor comes with two types of toolbar: the common TinyMCE toolbar and the custom toolbar.

The first image shows the default (native) toolbar, which comes with its own behavior for smaller screens.

Rich text editor – Native TinyMCE toolbar
Rich text editor – Native TinyMCE toolbar

The next image shows the custom toolbar, which includes common SAP Fiori controls and utilizes the overflow toolbar behavior. All common actions provided by the native toolbar are also offered by the custom toolbar.

Rich text editor – Custom SAP Fiori toolbar with overflow
Rich text editor – Custom SAP Fiori toolbar with overflow
Developer Hint
You can decide which toolbar to use. Bear in mind that the type of toolbar is only considered when control is being initialized. It cannot be changed during runtime because of lifecycle incompatibilities between SAPUI5 and the third-party library. You can enable the TinyMCE mobile theme, but once you do so, the native TinyMCE toolbar and layout are always loaded.

Actions in the Custom Toolbar

The custom toolbar includes most of the native TinyMCE actions. The actions are separated into several virtual groups. You can hide each group of actions individually if it is not required by the use case.

Rich text editor – Actions in the custom toolbar
Rich text editor – Actions in the custom toolbar

1) Font Styles: A group of four styles that can be applied to individual symbols (Bold, Italic, Underline and Strikethrough). All of the actions can be combined, which means that a preselected text can be bold, italicized, underlined and crossed out at the same time.

2) Align Text: A group of actions for aligning the text: Align Left, Align Right, Center and Justify. By default the text is left aligned. The selected style is applied to the entire paragraph.

3) Styles: Offers a list of predefined styles, including 6 heading levels and a paragraph. The default style is Paragraph.

4) Font: Changes the font family of the text. All the available fonts are displayed in a select control. 17 font families are supported, including popular fonts like Verdana, Tahoma, Arial, Times New Roman, and Helvetica. The change is applied to individual symbols.

5) Font Size: Changes the size of the text. All available font sizes are displayed in a select control. The minimum size is 8 pt and the maximum size is 36 pt. The change is applied to individual symbols.

6) Text Color: Opens a menu with different options for choosing the color of the text, including a color picker dialog. The default text color is black.

7) Background Color: Opens a menu with different options for choosing the color of the background, including a color picker dialog. The default background color is white.

8) List Type: Part of the structure group. There are two types of list: Bulleted List and Numbered List. This action is applied at paragraph level and turns a normal paragraph into a list. The two list types cannot be applied simultaneously.

9) Text Indent: Part of the structure group. These two actions let users increase or decrease the indentation of the text.

10) Link: A group with two actions: Insert/Edit Link and Remove Link.

11) Insert/Edit image: This option opens a dialog for adding and editing images. Users can also define some of the image properties, such as the width, height, and description.

12) Insert Table: Inserts a simple table within the content area.

13) Clipboard: This action group includes the Cut, Copy, and Paste actions.

14) Custom Action: If the use case requires an action that is not available in the set of common actions, you can attach an external plugin to the custom action. Technically, you can add as many custom actions as you like. However, because custom actions are displayed after the common actions, we recommend keeping the number of custom actions down to a reasonable level.

Developer Hint
The rich text editor is actually an SAPUI5 wrapper around the open source TinyMCE editor. TinyMCE’s functionality can easily be extended using plugins, which can also be attached to the custom toolbar.

The general approach for enabling 3rd-party TinyMCE plugins for the rich text editor is:

  1. Create or find a plugin.js file and place it in convenient place in your application. Alternatively, define the plugin directly in your code.
  2. Load or call the plugin after the TinyMCE core library has loaded. This can be done in the rich text editor’s beforeEditorInit hook.
  3. Add the plugin to the TinyMCE instance.
    • If you’ve defined the plugin directly in your code (synchronous), you can also enable the plugin in the beforeEditorInit hook.
    • If the plugin is in external file and is loaded asynchronously, the plugin should be registered in the instance when the plugin file is downloaded. A convenient place to enable the plugin is the rich text editor’s ready or readyRecurring event.
  4. Optional: If the rich text editor is instantiated with the custom toolbar, be sure to add a custom button to it to make the functionality available.

Important: Third-party plugins are not supported by SAP. We cannot guarantee that there will not be any issues with their enablement.

Behavior and Interaction

General Information

The rich text editor is only available in edit mode of the floorplan it is displayed in. In display mode the content is shown as it is formatted by the user. The user-defined formatting cannot be overwritten.

The toolbar is always visible and the user has access to all the action groups. To start typing, the user has to click inside the content area.

To apply any of the actions from the toolbar, the user has to select the text to be formatted upfront.

Some of the actions can be preselected and applied prior to typing the text. These actions are:

  • Font family, font size and styling (bold, italic, underline)
  • Paragraph alignment
  • Color selection (text color and background color)

Font Styles

The user selects the font style using the respective icon toggle buttons (Bold, Italic, Underline, Strikethrough). The style is applied to a preselected text and remains active until the user clicks the button again or moves the marker to an area where a different style is applied, or no style is applied.

Alignment

The user can change the alignment of the text (Align Left, Align Right, Center, Justify).

By default the text is left-aligned. The selected style is applied to the entire paragraph. To apply any of the styles, the user selects the text and then clicks on the Align Text button  . It is also possible to select the alignment upfront, but in this case only the text written after the selection will have the desired alignment.

Font

The user selects the desired font family from a list of all available font families. The selected font family can be applied to a preselected text, or selected upfront. The default font family is Verdana.

Font Size

The user selects the desired font size from a list of font sizes from 8 pt to 36 pt. The selected font size can be applied to a preselected text, or selected upfront.

List Types

The user can create two types of lists, both of which are triggered by toggle buttons: bulleted lists   and numbered lists  . List formatting is applied at paragraph level. To apply list formatting, the user preselects the relevant paragraphs and selects the relevant list type action.

Text Indent

The text indent defines the amount of empty space in front of a paragraph. The user can increase the indentation  , or decrease it  . Both actions are triggered by standard buttons, and are applied at paragraph level. To change the indentation, the user selects the paragraph (or just positions the cursor within the text) and selects the indent action. The text is moved 30 px left or right, depending on the action chosen.

Color Selection

The user can change the text color and the background color. The chosen colors can be applied to a preselected text or selected upfront.

To choose a color, the user clicks on the color arrow button for the font or background (the right-hand segment of the split button). This opens a popover where users can choose the default color (black for text, white for background), select one of 15 predefined colors, or open a separate color picker dialog.

Within the color picker dialog, the following options are available:

  • Move the circle inside the color field
  • Define RGB values
  • Define HSL values
  • Enter the HEX value
  • Use the horizontal color slider

Users can also define the transparency with the transparency slider.

Clicking OK confirms the selection.

The user can also apply the most recent font or background color without opening the color palette or the dropdown menu. This is done by pressing the left-hand segment of the split button.

Inserting, Editing, and Removing Links

The Insert/Edit Link button opens a dialog for entering the link details. These include the URL, the link text, a title, and the target for the link (same or new browser window) .

It is also possible to attach a link to a preselected text and to edit details for an existing link.

The Remove Link button   is only active when an existing text link has been selected.

Inserting and Editing Images

The Insert/Edit Image button opens a dialog for entering the image URL, a description, and the size.

Beforehand, the user must upload the image to a library that can be accessed by the application. In the dialog itself, users can only enter an existing image link. Images cannot be uploaded directly to the server.

To change the alignment of the inserted image, the user selects the image and applies the relevant alignment action. The text around the image is positioned as follows:

  • Right-aligned image: The text is displayed to the left of the image.
  • Left-aligned image: The text is displayed to the right of the image.
  • Centered image: Only the image is displayed in the center of the paragraph.

Users can also edit the URL, description, and size of an existing image by selecting the image and choosing Insert/Edit Image.

Guidelines

Minimum Width

Although the control allows a minimum width of 6 rem (96 px), we recommend setting the width to at least 17.5 rem (280 px). Any less will make the editor practically unusable.

Minimum Height

The minimum height of the control is 12.5 rem (200 px), which ensures that the editor is usable.

Number of Actions in the Toolbar

Only offer actions that are relevant for the use case. If you just need simple text formatting (such as bold, italic, underline, and strikethrough), remove the other groups.

Custom Plugins

Exercise judgement when adding custom plugins to the editor. Only offer a reasonable number of additional options.

Use self-explanatory icons for custom actions. Do not use a text label, or combine a text label with and icon.
As for all icons, offer a tooltip with a text label instead.

Additional Guidelines

The guidelines for the following controls also apply:

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Dynamic Date

The dynamic date is a smart control that is currently only available in the smart filter bar. When the user enters a value in the date field, it suggests corresponding fixed and dynamic dates. It also offers a value help feature that lets users choose between different time periods and define them further. The list of values offered must be defined by the app.

Information
The dynamic date control can only be used in the smart filter bar. If you are not using the smart filter bar, use the date range selection control instead.

Usage

Use the dynamic date control if:

  • You need flexibility between fixed and dynamic dates.
  • You need dynamic dates that can be saved in the variant management (for example, show values from today regardless of when you open the app).
  • You are using the smart filter bar.
  • The user only needs to select one value.

Do not use the dynamic date control if:

  • Users need to enter a date and a time. In this case, use the date picker or the date/time picker instead.
  • Selecting ranges is not the user’s primary goal. In this case, use the simple date picker.
  • You are not using the smart filter bar.

Responsiveness

The dynamic date control is fully responsive. It provides a touch-friendly screen in sizes S and M (cozy mode) and is smaller in size L (compact mode). For more information on cozy and compact modes, see the article on content density.

Value help for dynamic date range – Size S
Value help for dynamic date range – Size S
Value help for dynamic date range – Size L
Value help for dynamic date range – Size L

Components

The two clickable areas of the dynamic date control
The two clickable areas of the dynamic date control

The dynamic date consists of two components:
(A) Date input field with suggestions
(B) Value help popover

On all devices, users can either use the input field to type a date, or use the value help button to open the popover.

Dynamic Date Input Field

The user can type data directly into the input field. Upon user input, a list of suggestions appears.

Value Help Popover

The value help popover offers all available values the user can choose from. Depending on the selected time period, the popover shows different controls. It either shows:
(A) An input field
(B) One or two date pickers
(C) A read-only text with the chosen date range
(D) A select control

Value help popover – Input field
Value help popover – Input field
Value help popover – Date pickers
Value help popover – Date pickers
Value help popover – Read only
Value help popover – Read only
Value help popover – Select control
Value help popover – Select control

Values Offered

  • From
  • To
  • Date Range
  • Today
  • Today -X / +Y days
  • Last X days
  • Next X days
  • This week
  • Last week
  • Last X weeks

Offered Values

  • Next week
  • Next X weeks
  • Month
  • This month
  • Last month
  • Last X months
  • Next X months
  • This quarter
  • Last quarter
  • Last X quarters
  • Next quarter

Offered Values

  • Next X quarters
  • First quarter
  • Second quarter
  • Third quarter
  • Fourth quarter
  • This year
  • Last year
  • Last X years
  • Next year
  • Next X years
  • Year to date

Behavior & Interaction

Typing data into the date range input field

The user can type keywords or numbers into the date range input field.  For example, if the user types a number, the system automatically suggests possible dates. All dynamic dates show the actual dates to help the user select the right value.

List of suggestions shown after typed input
List of suggestions shown after typed input

Opening the value help and selecting a time period

Clicking the value help icon opens a popover with additional options for defining the time period. The user can choose from several time periods by clicking the down arrow in the select control. Once a time period has been chosen, the selection box closes.

Opening the value help popover and selecting a time period
Opening the value help popover and selecting a time period

Defining a custom time period (X)

If the user selects a custom time period with “X”, such as Last X days, the control shows a simple input field for entering the number. The text in the date input field changes according to the user’s input.

Custom time period with a simple input field
Custom time period with a simple input field

Selecting a date range

If the user selects a time period that requires input of a start and end date, two date pickers appear. These can be opened by clicking the calendar icon. The text in the date range input field changes according to the user’s input.

Selected time period with two date pickers (start date and end date)
Selected time period with two date pickers (start date and end date)

Styles

Validation

Use inline validation to give the user feedback, especially for errors and warnings. The possible states are “warning”, “error”, and “success”.

The dynamic date input field in question is highlighted by a frame in the corresponding color. If the focus is inside the field, an explanation is shown. Ensure that this explanation is as specific as possible.

Visible frame that shows an error when the field is out of focus
Visible frame that shows an error when the field is out of focus
Error state with meaningful text – The date range input field is in focus
Error state with meaningful text – The date range input field is in focus

Guidelines

See the Date Picker and Date Range Selection articles for the guidelines. They also apply to the dynamic date control.

 

List of Options

  • Only provide values that are relevant for the use case in the list of options.
  • You can also add your own values, if necessary.
  • If you use your own values, provide human readable text.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation

Checkbox

A checkbox lets the user set a binary value (such as “true/false”). When the user clicks the checkbox, it toggles between checked and unchecked. Checked means that the state described by the checkbox text applies, or that the item has been chosen.

The checkbox text describes the positive action (as in “true” or “yes”). The text can be either a label control to the left of the checkbox, or a checkbox text that appears to the right of the box.

  • If there is only one checkbox, you can use a label or text depending on the form format.
  • If there is more than one checkbox, the label describes the whole group of checkboxes. In this case, use the text property of the checkbox to describe the individual checkboxes.

Within a group of checkboxes, each checkbox can be checked or unchecked. The user can check multiple options.

A checkbox does not apply a setting right away; the changes take effect after user confirmation via a triggering action button (such as Save).

Checkbox enabled/disabled
Checkbox enabled/disabled

Usage

Use the checkbox control if:

  • Only one option can be selected or deselected, for example to accept terms of use. Use it only if the meaning is obvious (single checkbox).
  • You have a group or a list of options that can be selected independently of each other (checkbox group).
  • Your use case requires all available options to be displayed right away without any user interaction (also in read-only cases).
  • The values of the option list are primary information and need to be displayed right away.
  • Changes to the settings need to be confirmed and reviewed by the user before they are submitted. This helps prevent users from changing settings accidentally.
  • You want to group multiple suboptions under a parent option, and require an intermediate selection state (tri-state). The tri-state indicates that some (but not all) suboptions are selected.

Do not use the checkbox control if:

  • The user needs to choose multiple options from a large list. Use a multi-combo box instead.
  • The user can choose only one option from a list. For a small list, use a radio button group instead. For a large list, use the select control or a list with multi-selection functionality.
  • You want to offer two options for a “yes/no” or “on/off” type of decision. Consider using a switch control instead.
  • The user needs to perform instantaneous actions that do not need reviewing or confirming. Consider using the switch control instead.
  • There is not enough space available on the screen. Use the combo box control instead.

Responsiveness

A checkbox can appear in two different sizes. In cozy mode, it is bigger than it is in compact mode. This makes the checkbox easier to select on touch devices. For more information on cozy and compact modes, see the article on content density.

Compact and cozy mode
Compact and cozy mode

In both sizes, the touch/click area around the checkbox is bigger than the checkbox itself, making the checkbox easier to select. Clicking inside this area toggles the checkbox.

Note: Because the touch/click area does not include the label on the left, clicking the label will not toggle the checkbox.

Checkbox touch/click area without label
Checkbox touch/click area without label
Checkbox touch/click area with label
Checkbox touch/click area with label

Layout

The checkbox control consists of a box and a text that describes the purpose of the checkbox.

If the checkbox is checked, an indicator is shown inside the box.

Although the clickable area to select/deselect a checkbox covers a wider area than the box (see the Responsiveness section), the focus is indicated by a dotted line that surrounds only the box.

If the checkbox appears alone inside a form, the text can be omitted if the label in front of the checkbox takes over its function.

Note: Because the touch/click area does not include the label on the left, clicking the label does not toggle the checkbox.

If there are several options to choose from in a form, the label describes the entire checkbox group, and the texts describe the individual checkboxes.

Since checkbox texts are also a type of label, use title case to be consistent with other labels. If the label is long, it can wrap in order to fit the text into the visible area of the content holder. There is no limit on the number of lines a text can wrap.

Exception: If one or several of the checkbox texts is very long, or is formulated as a phrase, use sentence case and appropriate ending punctuation.

For forms with labels above the fields, place the label above the checkbox group, or do not use a label. For a single checkbox, use only a checkbox text.

For forms with labels to the left of the field, place the label next to the group, aligned with the first checkbox field, or do not use a label. For a single checkbox, use only a label, or only a checkbox text.

Developer Hint
Do not use empty labels to arrange the checkboxes. Creating a label in front of each checkbox and leaving the text empty looks fine – nobody sees the label, and the checkboxes are aligned correctly underneath each other. However, the screen reader will notice these labels and read each of them as “label”. Instead, use the layout data property (layoutData) for the checkbox. In this property, force a line break (linebreak) and set the value of the indents in sizes L and M (indentL, indentM) according to the value of the label span in the simple form (labelSpanL, labelSpanM).
Checkbox layout
Checkbox layout
Short checkbox text in title case; Long checkbox text in sentence case
Short checkbox text in title case; Long checkbox text in sentence case
Checkbox text wrap
Checkbox text wrap
Checkbox group with label aligned to the left or on top
Checkbox group with label aligned to the left or on top
Checkbox group without label
Checkbox group without label
Single checkbox with label or with text
Single checkbox with label or with text

Behavior and Interaction

Clicking a checkbox toggles the state of the checkbox between checked and unchecked.

Tri-State

The main purpose of this state is to represent the mixed selection states of dependent input fields. If some (but not all) of the dependent fields are selected, the checkbox shows a partially selected state. This is only a visual state and can’t be achieved by a direct user interaction.

Checkbox interaction states
Checkbox interaction states

Properties

You can set the width of the element containing the checkbox and the text manually (property: width).

If the text exceeds the available width, it can wrap. The touchable area for toggling the checkbox ends where the text ends.

If the width allows more space than the text requires, white space is added. The touchable area for toggling the checkbox is increased according to the manually-set width.

The text can be positioned manually in this space (property: textAlign). However, we do not recommend using the right-align option, which can result in a large amount of white space between the checkbox and the checkbox text.

States

If a checkbox is part of an editable form, it can be edited in when the form is in edit mode. In display mode, the checkbox uses its “display-only” state (property: displayOnly), and two icons replace it to represent the checked and unchecked states.

If the checkbox appears in a read-only form, set the checkbox to read-only (property editable = “false”).

Do not combine the settings “disabled” and “read-only”. This is technically possible, but does not make any sense.

The checkbox can represent a mixed selection state, or tri-state (property: partiallySelected). The visual state depends on the value of the selected property.

Don't
Checkbox text - Don't format the checkbox incorrectly
Checkbox text - Don't format the checkbox incorrectly
Checkbox interaction value states
Checkbox interaction value states

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation