Archives

Form

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other components (such as labels, input fields, checkboxes, and sliders), which are structured in a specific layout.

Form - display and edit views
Form - display and edit views

When to Use

Do

Use the form:

  • When you require data input from the user to collect information (for example, in a survey or application form).
  • When the user can edit or enhance data that is already available.
Don't

Don’t use the form:

  • For presenting and editing a set of repeating data. Use a table instead.

Top Tips

  • Order the form logically from a user’s perspective. For example, ask for a user’s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • If an input element is in an error or warning state, provide a meaningful message for the user.
  • If you display the unit of measurement after the input field, make sure that it’s properly visualized and doesn’t wrap to the next row.
  • When the form is in edit view, right-align amounts to avoid gaps between the amount and the unit of measurement.
  • When a form is in display view, left-align amounts to avoid large gaps between the labels and values.
  • If the expected input isn’t obvious from the label alone, provide a brief placeholder (word or phrase) as a hint to help the user with data entry.

Anatomy

Structure

A form is structured into form containers. Each form container consists of form elements.

  1. Container: The form is the top-level container component. It controls the content layout and the responsiveness.
  2. Group: The form group enables grouping of the form content.
  3. Form item: A pair of label and form field.
Structure of a single form container
Structure of a single form container

Form Components

A simple form consists of a header area and a content area with pairs of label and form field.

  1. Header area: The header area is on top and displays a header text.
  2. Label: The label of a single form item. It serves as the name of the input field.
  3. Value: In display mode, the value is read only. In edit mode, a value can be added or edited.
Anatomy of a simple form
Anatomy of a simple form

Variants

Form Variants

Form with Custom Header

You can use a custom form header (for example, with additional buttons).

Simple form with custom header
Simple form with custom header

Freestyle Form

The freestyle form gives you full control of the form and its elements.

Freestyle form
Freestyle form

Layout Variants

Single Form on a Page

A single form can contain one or more groups.

Form with only one group and a header title
Form with only one group and a header title

Form with two groups and no header title
Form with two groups and no header title
Guidelines

  • If a form contains only one group, don’t use a group title. Instead, use the form title.
  • If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups.


Multiple Forms on a Page

You can also use multiple forms on one page. Separate forms are more distinct visually than groups within a form.

Two forms on one page
Two forms on one page

Two forms on one page, with form groups
Two forms on one page, with form groups
Guidelines

  • For clearer group separation, use several forms on a page instead of a single form with multiple groups.
  • Provide a meaningful title for each form.
  • If needed, also use group titles within each form.


Label-Value Alignment

You can align labels vertically or horizontally.

Vertical alignment: The vertically-aligned form best supports the reading flow and avoids unnecessary eye movements.

Horizontal alignment: If there is enough space, the label can be right-aligned next to the value.

Form - vertical alignment
Form - vertical alignment


Form - horizontal alignment
Form - horizontal alignment

Form Group Span

Form groups can be distributed into one or more columns.

Example:
Group More Information spans two columns.

Form group split into two columns
Form group split into two columns

Form Item Span

A form item can span several columns.

Example:
Form item “Full Name” spans in two columns.

Form item spanning two columns
Form item spanning two columns

Features

Label for Required Fields

The label of a required field is marked with an asterisk (*).

The asterisk is visible in edit view only.

Required field marked with an asterisk (*)
Required field marked with an asterisk (*)

Empty State Indicator

If a form field doesn’t have a value, an empty state indicator is shown by default in read-only mode.

The indicator helps the user to better scan the form and perceive the field label and empty content as one unit.

If a field is empty in the edit view, there is no empty state indicator. The field is either empty or displays a placeholder text, if defined.

Empty state indicator in a form (display view)
Empty state indicator in a form (display view)

Behavior and Interaction

The visual appearance of the form depends on the component state of the form fields. As a result, three form views are possible: display, edit, and edit with read-only fields.

Display View

The data is presented as label-value field pairs, without editable fields.

Form in display view
Form in display view

Edit View

The data is presented as label-input fields pairs, so users can enter or edit data.

Form in edit view
Form in edit view

Edit View with Read-Only Fields

Some fields are editable and some are not (shown in read-only state).

Form in edit view with read-only fields
Form in edit view with read-only fields

Responsive Behavior

Breakpoints

The form component reacts and changes its layout on predefined breakpoints. Depending on its size, the form content gets divided into one or more columns.

Example

S1 M2 L3 XL6: 1 column for S, 2 columns for M, 3 columns for L, and 6 columns for XL.

Form with breakpoint – Size S
Form with breakpoint – Size S
Form with breakpoint – Size M
Form with breakpoint – Size M
Form with breakpoint – Size L
Form with breakpoint – Size L

Group Spreading

If a form contains more than one group, the group with the most items wraps with priority by default. In the XL example below, the Contact and Address groups each span two columns.

Form in size XL with 6 columns and groups that span 2 and 3 columns.
Form in size XL with 6 columns and groups that span 2 and 3 columns.

Wrapping

To avoid text truncation, all values and labels within a form wrap by default.

Wrapped labels and texts in a form
Wrapped labels and texts in a form

By default, form titles wrap up to 3 rows and then truncate.

Form header wrapping and truncation
Form header wrapping and truncation

Alignment

If there isn’t enough space to show a horizontally-aligned form, the display switches to vertical alignment.

Form Label Span

The width ratio of the label and form field can be defined by a breakpoint.

Label-field distribution in a form
Label-field distribution in a form

Related Links

Components

Implementation

  • Form
    (UI5 Web Components documentation)

Specifications

  • Form (visual design)
  • Form (interaction design)

Carousel

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

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

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

Usage

Use the carousel if:

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

Do not use the carousel if:

  • The items you want to display are uniform.

Responsiveness

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

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

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

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

Carousel - Size S
Carousel - Size S

Carousel - Size M
Carousel - Size M

Carousel - Size L
Carousel - Size L

Layout

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

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

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

Displaying multiple items

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

Behavior and Interaction

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

Navigation for Single Items

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

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

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

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

Paging button – Previous page
Paging button – Previous page
Paging button – Next page (hover)
Paging button – Next page (hover)

Navigation for Multiple Items

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

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

Carousel with multiple items
Carousel with multiple items

Looping

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

Paging

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

Paging indicator - Icons
Paging indicator - Icons

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

Paging indicator - Count
Paging indicator - Count

Resources

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

Elements and Controls

Image (guidelines)

Implementation

Carousel

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

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

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

Usage

Use the carousel if:

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

Do not use the carousel if:

  • The items you want to display are uniform.

Responsiveness

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

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

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

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

Carousel - Size S
Carousel - Size S

Carousel - Size M
Carousel - Size M

Carousel - Size L
Carousel - Size L

Layout

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

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

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

Displaying multiple items

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

Behavior and Interaction

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

Navigation for Single Items

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

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

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

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

Paging button – Previous page
Paging button – Previous page
Paging button – Next page (hover)
Paging button – Next page (hover)

Navigation for Multiple Items

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

Carousel with multiple items
Carousel with multiple items

Looping

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

Paging

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

Paging indicator - Icons
Paging indicator - Icons

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

Paging indicator - Count
Paging indicator - Count

Resources

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

Elements and Controls

Image (guidelines)

Implementation

Card

A card represents an app or page. It can be used to launch the app or navigate to the page content. Integration cards are a way of making application content available to end users in a consistent manner.

Integration cards are similar to the cards on the overview page. However, unlike the overview page cards, integration cards can be used in different host environments.

A card can show details about a single app or page, or contain related information from multiple sources. An app or page can also be represented by several cards, which each focus on a different aspect of the content.

Card examples
Card examples

When to Use

You can offer cards on the SAP Fiori launchpad or embed them in other controls.

Offer a card if:

  • You want to give users easy access to an app or page that is relevant for a business task.
  • You want to show a KPI or a preview of the most important content for the task.
  • You want to let users complete a simple action right away, without navigating to the underlying app.

Card Anatomy

A card comprises a header and a content area, which are separated by a divider line. Both components are inside a card container, which includes the background and the border.

Header

The header shows what the card is about. There are two variants: the default header and the numeric header.

Card structure
Card structure

Default Header

The default header shows the basic information about the card and has the following components:

  1. The title is mandatory and represents the “point of view” of the card. Titles longer than three lines are truncated with an ellipsis (…).
  2. Optional: You can use a subtitle to qualify the title or explain the context. Subtitles that exceed two lines are truncated.
  3. Optional: You can use an avatar to provide a visual hint on the card header (for example, an image, icon, or initials).
  4. If the content area contains multiple items, a counter is added to the header. It shows how many items are visible on the card in relation to the total number of relevant items (for example, “6 of 12”).
Default header
Default header

Numeric Header

Use the numeric header if you need to display numeric information.

  1. Mandatory title
  2. You can add a subtitle with additional qualifying information (optional).
  3. If you specify a currency or unit of measurement, it also appears in the subtitle row. If you provide both a subtitle and a unit of measurement, the display format is: <subtitle text> | <unit of measurement>.
  4. In additional to the general information, you can configure the visualization for a numeric value, such as a KPI.
  5. If required, you can also show up to two additional indicators that relate to the main KPI.
  6. If required, you can display more information about the numeric value directly below it (for example, the period for which a KPI applies).
Numeric header
Numeric header
Guidelines
Ensure that the card title is short, clear and precise.

Provide all the information required to interpret the numeric value (specific description, currency or unit of measurement, relevant period).

  • For currencies and standard units of measurement, use the dedicated unitOfMeasurement property. The unit then appears consistently in the subtitle line. If the value is a simple count (such as the number of open tasks), a precise title/subtitle text is usually sufficient.
  • If the value applies to a period, use the footer area (5) to specify the period.

Content Area

The content area is reserved for showing information from the underlying source(s). Cards can represent different types of content, with several visualization options. This depends on which card type is used.

Guidelines
In the card content area, show the most relevant data for the task at hand.

Card Types

The card type defines how content is presented (for example, as a list or table). The embedded controls govern the layout, navigation, and interaction in the card content area.

The following card types are available:

List Card

The list card can display multiple list items of various types.

Schematic example of a list card
Schematic example of a list card

Analytical Card

The analytical card visualizes analytics data. It can contain a line chart, bar chart, or donut chart.

Schematic example of an analytical card
Schematic example of an analytical card

Table Card

The table card displays multiple items in a table view.

Schematic example of a table card
Schematic example of a table card

Object Card

You can use this card type to display information about an object in groups. Each group can contain as many items as needed.

Schematic example of an object card
Schematic example of an object card

Timeline Card

The timeline card displays time-related content in chronological order.

Schematic example of a timeline card
Schematic example of a timeline card

Calendar Card

The calendar card shows the schedule for a single entity (typically a person) for a selected day.

Schematic example of a calendar card
Schematic example of a calendar card

Component Card

The component card allows you to display a SAPUI5 component as content. This gives you significant flexibility in configuring the content.

Behavior and Interaction

Card Header

The whole header is clickable and is the navigation area for opening the underlying source. Clicking the header opens the app or page that relates to the card.

Card Content

The content area can have several click areas with different purposes. They depend on the control used and the structure of the content.

Guidelines
Always provide meaningful navigation targets. Ensure that the navigation target supports the information flow that starts on the card.
Card interaction
Card interaction

Responsiveness

The responsive behavior for integration cards depends on the container control of the host environment (for example, SAP Fiori launchpad). The size of the card adapts dynamically to the size of the container.

Top Tips

  • Cards introduce users to the content in the underlying source. Make sure that your card focuses on the most relevant content.
  • Use cards if supportive visualizations and meaningful navigations are helpful for users.
  • Don’t use individual branding.
  • Avoid unnecessary white space on the card.

Related Links

Elements and Controls

Implementation

Card

A card represents an app or page. It can be used to launch the app or navigate to the page content. Integration cards are a way of making application content available to end users in a consistent manner.

Integration cards are similar to the cards on the overview page. However, unlike the overview page cards, integration cards can be used in different host environments.

A card can show details about a single app or page, or contain related information from multiple sources. An app or page can also be represented by several cards, which each focus on a different aspect of the content.

Card examples
Card examples

When to Use

You can offer cards on the SAP Fiori launchpad or embed them in other controls.

Offer a card if:

  • You want to give users easy access to an app or page that is relevant for a business task.
  • You want to show a KPI or a preview of the most important content for the task.
  • You want to let users complete a simple action right away, without navigating to the underlying app.

Card Anatomy

A card comprises a header and a content area, which are separated by a divider line. Both components are inside a card container, which includes the background and the border.

Header

The header shows what the card is about. There are two variants: the default header and the numeric header.

Card structure
Card structure

Default Header

The default header shows the basic information about the card and has the following components:

  1. The title is mandatory and represents the “point of view” of the card. Titles longer than three lines are truncated with an ellipsis (…).
  2. Optional: You can use a subtitle to qualify the title or explain the context. Subtitles that exceed two lines are truncated.
  3. Optional: You can use an avatar to provide a visual hint on the card header (for example, an image, icon, or initials).
  4. If the content area contains multiple items, a counter is added to the header. It shows how many items are visible on the card in relation to the total number of relevant items (for example, “6 of 12”).
Default header
Default header

Numeric Header

Use the numeric header if you need to display numeric information.

  1. Mandatory title
  2. You can add a subtitle with additional qualifying information (optional).
  3. If you specify a currency or unit of measurement, it also appears in the subtitle row. If you provide both a subtitle and a unit of measurement, the display format is: <subtitle text> | <unit of measurement>.
  4. In additional to the general information, you can configure the visualization for a numeric value, such as a KPI.
  5. If required, you can also show up to two additional indicators that relate to the main KPI.
  6. If required, you can display more information about the numeric value directly below it (for example, the period for which a KPI applies).
Numeric header
Numeric header
Guidelines
Ensure that the card title is short, clear and precise.

Provide all the information required to interpret the numeric value (specific description, currency or unit of measurement, relevant period).

  • For currencies and standard units of measurement, use the dedicated unitOfMeasurement property. The unit then appears consistently in the subtitle line. If the value is a simple count (such as the number of open tasks), a precise title/subtitle text is usually sufficient.
  • If the value applies to a period, use the footer area (5) to specify the period.

Content Area

The content area is reserved for showing information from the underlying source(s). Cards can represent different types of content, with several visualization options. This depends on which card type is used.

Guidelines
In the card content area, show the most relevant data for the task at hand.

Card Types

The card type defines how content is presented (for example, as a list or table). The embedded controls govern the layout, navigation, and interaction in the card content area.

The following card types are available:

List Card

The list card can display multiple list items of various types.

Schematic example of a list card
Schematic example of a list card

Analytical Card

The analytical card visualizes analytics data. It can contain a line chart, bar chart, or donut chart.

Schematic example of an analytical card
Schematic example of an analytical card

Table Card

The table card displays multiple items in a table view.

Schematic example of a table card
Schematic example of a table card

Object Card

You can use this card type to display information about an object in groups. Each group can contain as many items as needed.

Schematic example of an object card
Schematic example of an object card

Timeline Card

The timeline card displays time-related content in chronological order.

Schematic example of a timeline card
Schematic example of a timeline card

Calendar Card

The calendar card shows the schedule for a single entity (typically a person) for a selected day.

Schematic example of a calendar card
Schematic example of a calendar card

Component Card

The component card allows you to display a SAPUI5 component as content. This gives you significant flexibility in configuring the content.

Behavior and Interaction

Card Header

The whole header is clickable and is the navigation area for opening the underlying source. Clicking the header opens the app or page that relates to the card.

Card Content

The content area can have several click areas with different purposes. They depend on the control used and the structure of the content.

Guidelines
Always provide meaningful navigation targets. Ensure that the navigation target supports the information flow that starts on the card.
Card interaction
Card interaction

Responsiveness

The responsive behavior for integration cards depends on the container control of the host environment (for example, SAP Fiori launchpad). The size of the card adapts dynamically to the size of the container.

Top Tips

  • Cards introduce users to the content in the underlying source. Make sure that your card focuses on the most relevant content.
  • Use cards if supportive visualizations and meaningful navigations are helpful for users.
  • Don’t use individual branding.
  • Avoid unnecessary white space on the card.

Related Links

Elements and Controls

Implementation

Side Panel

Intro

The side panel is a feature located on the side of an app page, and provides quick access to frequently used actions and content without leaving the page. It can easily be expanded and collapsed, depending on the user’s needs.

The side panel is reserved for:

  • Additional context and information related to the overall page content or to an item on the page.
  • Interactive tools, such as actions and list elements.

The side panel can be positioned on the right or left side of the main page content. It can contain multiple tabs or a single tab. When expanded, the side panel pushes the main page content sideways.

Collapsed side panel
Collapsed side panel
Expanded side panel
Expanded side panel

When to Use

Do

You can use the side panel to give users easy access to information relating to the main content, such as comments, attachments, or a change log.

SAP S/4HANA Only

You can use the side panel together with a list report, worklist, or analytical list page.

Use the side panel only for the following use cases:

  • Comments
  • Attachments
  • Table filter and layout for pivot tables
  • Message handling and notifications
  • Activity history / change log
Don't

Don’t use the side panel:

  • In the object page floorplan. Use the dynamic side content instead.
  • In the flexible column layout.
  • As a navigation tool.
  • To provide controls or information that are unrelated to the content of the app page.

Components

The side panel has the following components:

1. Content panel icon and title.

2. Content area

3. Resize handle (optional)

4. Close button

5. Side bar

6. Expand/Collapse side panel

7. Icon tab (selected)

8. Icon tab (not selected)

9. Overflow button. See Multiple actions with overflow.

Guidelines
We recommend offering a maximum of 5 actions in a side panel.

Panel Width

By default, the side panel is 320 px wide when expanded. You change this setting as needed for your use case.

Side panel components
Side panel components

Behavior and Interaction

Side Bar and Content Panel Navigation

By default, the side panel is collapsed and no tabs are selected. You can change this as needed for your use case.

The interaction depends on how many actions you offer via the side panel.


Side bar with one action

If only one action is available, the side bar contains only the expand/collapse button.

The expand button  opens the content panel. The collapse button  closes it.

On mouseover, the expand button  shows a tooltip with the name of the action.

Guidelines
Ensure that the tooltip text for the Expand button matches the title of the content area.

Side bar with multiple actions

Clicking a tab in the side bar opens the corresponding content panel directly.

To close the content panel, users can either click the tab in the side bar again or use the Close button at the top of the content panel.

Information
Ensure that the tooltip for the icon tab matches the title of the content area.

The Expand  button  at the top of the side bar expands the side bar. The available actions are now visible in full. The Collapse button  collapses the side bar again.

From the list of actions, users can navigate to the individual content panels. Opening a content panel collapses the side bar and the tab displays as selected.

Multiple actions with overflow

If the side bar can’t accommodate all the available actions, or the screen size is reduced, an overflow button (…) appears as the last option.

Clicking the overflow button opens a list of additional actions.

Users can close the list by:

  • Selecting an item
  • Clicking the overflow button again
  • Clicking anywhere else on the screen

Resizing the Content Panel

You can allow users to adjust the width of the content panel.

Mouse Interaction

  • Click and drag the resize handle to the left or to the right.
  • Double-click the resize handle to adjust the side panel width size as follows: Maximum width minimum width default width
  • Right-click the resize handle or anywhere within the side panel to open the context menu with the following options:
    • Expand to Maximum Width
    • Collapse to Minimum Width
    • Reset to Default Width

Keyboard Interaction

  • Press Left Arrow or Right Arrow to expand or collapse the panel by 10 px.
  • Press Shift+Left Arrow or Shift+Right Arrow to expand or collapse the panel by 100 px.

Screen Width Limits

For legibility, we recommend limiting the screen width allowed for the side panel display as follows:

  • Maximum: 90% of the screen
  • Minimum: 15% of the screen

You can change these values, depending on the use case.

If the app page contains two side panels – one to the left and one to the right of the screen – the expanded side panel is limited to 50% of the screen width. Users can only expand one panel at once.

Guidelines
To keep your UI simple, avoid using more than one side panel.

Accessibility

Users can perform all the following actions with both a mouse and keyboard:

  • Expand and collapse the side bar
  • Select and deselect the tabs on the side bar to open and close the content panel
  • Set the focus on a tab
  • Move the focus from the side bar to the content panel
  • Resize the side panel

Responsiveness

Information on the design for tablet and phone devices will be added soon.

Related Links

Elements and Controls

Implementation

Block Layout

Information
The controls described in this article have been designed exclusively for the SAP tool landscape for the SAP Cloud Platform. Do not use these controls in regular SAP Fiori applications. This highly specialized set of controls targets the specific needs of the tools user group (typically developers and administrators).

These additional controls are created and maintained by the SAP Cloud Platform Design team. If you have questions about the controls or tool development in general, feel free to reach out to us through the SAP Fiori Design Community.

Information
This page is no longer being updated. For the latest updates, see Block Layout in the BTP Design Toolkit.

Intro

The block layout is used to display content in a section-based manner. It features horizontal and vertical subdivisions and full-width banners seen frequently in contemporary web design. Background colors are attached directly to these areas within the layout. Also, special full-width sections of the block layout enable horizontal scrolling through a set of areas.

General page structure of a tool using the block layout
General page structure of a tool using the block layout

Usage

Use the block layout if:

  • You want to display section-based content. Place elements next to each other to indicate a content relationship.

Do not use the block layout if:

  • You want to display properties or features of one content item. Use the object page floorplan instead.
  • You want to display KPIs in the dashboard-variant. Use the overview page or a layout using cards instead.

Block layout case examples include landing pages and catalog-like pages.

In landing pages, the block layout may serve as a banner-like presentation of illustrative icons with associated text. By placing pictorial and textual elements side by side in different areas, a content relationship is established. In catalog-like layouts, the block layout serves as a flexible container for diverging content, such as headings, explanatory texts, code snippets, remarks, and examples.

It is also possible to have clickable blocks with their own hover and pressed states.

Layout

The block layout is divided into horizontal sections, which take on the full width of the available screen real estate. Their screen height is determined by their inner content, which prevents vertical scrolling.

If needed, the width of sections can also be set to the following predefined ratios (for the sizes XL, L and M):

  • 1 block: 100%
  • 2 blocks:
    • 50% and 50% or
    • 75% and 25% or
    • 25% and 75%
  • 3 blocks:
    • 3 × 33% or
    • 2 × 25% and 50% or
    • 50% and 2 × 25% or
    • 25% and 50% and 25%
  • 4 blocks: 4 × 25%

Block layouts can also contain sections that allow horizontal scrolling. These sections always have a width of 100%.

Schematic block layout
Schematic block layout
Schematic block layout with a section scrolling horizontally
Schematic block layout with a section scrolling horizontally

Components

Block layout components
Block layout components

1 – Section

1a – Section Title

2 – Block

2a – Block Title – can be text or a link.

2b – Block Body – can contain text or other controls.

Guidelines

  • Links within a block must lead to areas outside of the block. In addition, controls must update only their own containers.
  • Usage of disabled, emphasized or subtle links as block titles is not recommended. Dark background designs, for example when using the Accent variant, are not fully supported with regards to accessibility when used with links as titles.

Types

There are four types of block layouts:

  1. Default: This layout does not use any background colors.
  2. Dashboard: This layout type uses white blocks with spacing around them, making each block look like a card.
  3. Light: Areas use predefined colors found in the SAP Fiori 3 Quartz Light theme. These colors follow a specific order that is defined in the control. If there are more than six areas, the background colors start over beginning with the initial color.
  4. Accent: Each row contains a range of colors derived from one accent color, and these colors are used alternately. If required by the control, you can display multiple gray blocks: the different shades of gray will then be displayed alternately, beginning with the initial color.

Light Color Set

For the Light variant, use colors as follows:

  • block color A for the section title block.
  • block colors B, C, D, E, F and G for the blocks, one after another.
  • block color H for the footer.
Color set for the
Color set for the "Light" block layout type

Accent Color Sets

Row (Section) Color Sets

For the Accent variant of the block layout, you can use a different color set for each row (sap.ui.layout.BlockLayoutRow, property:rowColorSet). This enables different starting colors for the row coloring, and prevents color coalescence in the responsive behavior of the block layout.

Cell (Block) Colors

There are 10 predefined color sets that you can use as accent variants, each with 6 different shades.

To change the background of a particular block, set the desired color set (sap.ui.layout.BlockLayoutCell, property: backgroundColorSet) and color shade (sap.ui.layout.BlockLayoutCell, property: backgroundColorShade) accordingly.

Color set 1, with shades A to F
Color set 1, with shades A to F
Color set 4, with shades A to F
Color set 4, with shades A to F
Color set 7, with shades A to F
Color set 7, with shades A to F
Color set 10, with shades A to F
Color set 10, with shades A to F
Color set 2, with shades A to F
Color set 2, with shades A to F
Color set 5, with shades A to F
Color set 5, with shades A to F
Color set 8, with shades A to F
Color set 8, with shades A to F
Color set 3, with shades A to F
Color set 3, with shades A to F
Color set 6, with shades A to F
Color set 6, with shades A to F
Color set 9, with shades A to F
Color set 9, with shades A to F

Images

Images may be placed as background images within one block. The predefined paddings do not apply to blocks with images; images fill out the entire block.
If needed, the title control may be placed on top of the images.

Responsiveness

The block layout offers responsive behavior. There are three breakpoints, which results in four supported sizes: XL, L, M, and S. As with the responsive grid (another generic layout control), these breakpoints apply both to the page and block layout. However, the page layout’s breakpoints react to screen width, whereas the breakpoints of the block layout react to the width of the control itself.

Ratios of areas in different contexts

Blocks per section XL, L M S
1

(Block 1)

 100%  100% 100%
2

(Blocks 2-3)

 75% and 25%
or
25% and 75%		 75% and 25%
or
25% and 75%		 100% each*
100% each*
2

(Blocks 4-5)

 50% and 50%  50% and 50% 100% each*
3

(Blocks 6-8)

 3 × 33%  3 × 33% 100% each*
3

(Blocks 9-11)

 2 × 25% and 1 × 50%
or
1 × 50% and 2 × 25%
or
1 × 25%, 1 × 50% and 1 × 25%		 2 × 50% and 1 × 100% over two rows
or
1 × 100% and 2 × 50% over two rows		 100% each*
100% each*
100% each*
4

(Blocks 12-15)

 4 × 25%  2 × 50% over two rows 100% each*

*Blocks wrap and are displayed underneath each other

Responsive behavior - Size XL
Responsive behavior - Size XL
Responsive behavior - Size M
Responsive behavior - Size M
Responsive behavior - Size S
Responsive behavior - Size S

Sections with Horizontal Scrolling

The width of the horizontal scrolling area in different device contexts:

 

Blocks per section XL, L M S
3 – 5 40% 40% 90%
6 – 10 22.5% 40% 90%
Responsive behavior of a section with horizontal scrolling - Size L
Responsive behavior of a section with horizontal scrolling - Size L
Responsive behavior of a section with horizontal scrolling - Size M
Responsive behavior of a section with horizontal scrolling - Size M
Responsive behavior of a section with horizontal scrolling - Size S
Responsive behavior of a section with horizontal scrolling - Size S

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

Block Layout

Information

This layout has been designed specifically for the tool landscape for the SAP Cloud Platform. It is not intended for use in regular SAP Fiori applications. 

Information
This page is no longer updated. For the latest updates, see Block Layout in the BTP Design Toolkit.

Intro

The block layout is used to display content in a section-based manner. It features horizontal and vertical subdivisions and full-width banners seen frequently in contemporary web design. Background colors are attached directly to these areas within the layout. Also, special full-width sections of the block layout enable horizontal scrolling through a set of areas.

General page structure of a tool using the block layout
General page structure of a tool using the block layout

Usage

Use the block layout if:

  • You want to display section-based content. Place elements next to each other to indicate a content relationship.

Do not use the block layout if:

  • You want to display properties or features of one content item. Use the object page floorplan instead.
  • You want to display KPIs in the dashboard-variant. Use the overview page or a layout using cards instead.

Block layout case examples include landing pages and catalog-like pages.

In landing pages, the block layout may serve as a banner-like presentation of illustrative icons with associated text. By placing pictorial and textual elements side by side in different areas, a content relationship is established. In catalog-like layouts, the block layout serves as a flexible container for diverging content, such as headings, explanatory texts, code snippets, remarks, and examples.

It is also possible to have clickable blocks with their own hover and pressed states.

Layout

The block layout is divided into horizontal sections, which take on the full width of the available screen real estate. Their screen height is determined by their inner content, which prevents vertical scrolling.

If needed, the width of sections can also be set to the following predefined ratios (for the sizes XL, L and M):

  • 1 block: 100%
  • 2 blocks:
    • 50% and 50% or
    • 75% and 25% or
    • 25% and 75%
  • 3 blocks:
    • 3 × 33% or
    • 2 × 25% and 50% or
    • 50% and 2 × 25% or
    • 25% and 50% and 25%
  • 4 blocks: 4 × 25%

Block layouts can also contain sections that allow horizontal scrolling. These sections always have a width of 100%.

Schematic block layout
Schematic block layout
Schematic block layout with a section scrolling horizontally
Schematic block layout with a section scrolling horizontally

Components

Block layout components
Block layout components

1 – Section

1a – Section Title

2 – Block

2a – Block Title – can be text or a link.

2b – Block Body – can contain text or other controls.

Guidelines

  • Links within a block must lead to areas outside of the block. In addition, controls must update only their own containers.
  • Usage of disabled, emphasized or subtle links as block titles is not recommended. Dark background designs, for example when using the Accent variant, are not fully supported with regards to accessibility when used with links as titles.

Types

There are four types of block layouts:

  1. Default: This layout does not use any background colors.
  2. Dashboard: This layout type uses white blocks with spacing around them, making each block look like a card.
  3. Light: Areas use predefined colors found in the SAP Fiori 3 Quartz Light theme. These colors follow a specific order that is defined in the control. If there are more than six areas, the background colors start over beginning with the initial color.
  4. Accent: Each row contains a range of colors derived from one accent color, and these colors are used alternately. If required by the control, you can display multiple gray blocks: the different shades of gray will then be displayed alternately, beginning with the initial color.

Light Color Set

For the Light variant, use colors as follows:

  • block color A for the section title block.
  • block colors B, C, D, E, F and G for the blocks, one after another.
  • block color H for the footer.
Color set for the
Color set for the "Light" block layout type

Accent Color Sets

Row (Section) Color Sets

For the Accent variant of the block layout, you can use a different color set for each row (sap.ui.layout.BlockLayoutRow, property:rowColorSet). This enables different starting colors for the row coloring, and prevents color coalescence in the responsive behavior of the block layout.

Cell (Block) Colors

There are 10 predefined color sets that you can use as accent variants, each with 6 different shades.

To change the background of a particular block, set the desired color set (sap.ui.layout.BlockLayoutCell, property: backgroundColorSet) and color shade (sap.ui.layout.BlockLayoutCell, property: backgroundColorShade) accordingly.

Color set 1, with shades A to F
Color set 1, with shades A to F
Color set 4, with shades A to F
Color set 4, with shades A to F
Color set 7, with shades A to F
Color set 7, with shades A to F
Color set 10, with shades A to F
Color set 10, with shades A to F
Color set 2, with shades A to F
Color set 2, with shades A to F
Color set 5, with shades A to F
Color set 5, with shades A to F
Color set 8, with shades A to F
Color set 8, with shades A to F
Color set 3, with shades A to F
Color set 3, with shades A to F
Color set 6, with shades A to F
Color set 6, with shades A to F
Color set 9, with shades A to F
Color set 9, with shades A to F

Images

Images may be placed as background images within one block. The predefined paddings do not apply to blocks with images; images fill out the entire block.
If needed, the title control may be placed on top of the images.

Responsiveness

The block layout offers responsive behavior. There are three breakpoints, which results in four supported sizes: XL, L, M, and S. As with the responsive grid (another generic layout control), these breakpoints apply both to the page and block layout. However, the page layout’s breakpoints react to screen width, whereas the breakpoints of the block layout react to the width of the control itself.

Ratios of areas in different contexts

Blocks per section XL, L M S
1

(Block 1)

 100%  100% 100%
2

(Blocks 2-3)

 75% and 25%
or
25% and 75%		 75% and 25%
or
25% and 75%		 100% each*
100% each*
2

(Blocks 4-5)

 50% and 50%  50% and 50% 100% each*
3

(Blocks 6-8)

 3 × 33%  3 × 33% 100% each*
3

(Blocks 9-11)

 2 × 25% and 1 × 50%
or
1 × 50% and 2 × 25%
or
1 × 25%, 1 × 50% and 1 × 25%		 2 × 50% and 1 × 100% over two rows
or
1 × 100% and 2 × 50% over two rows		 100% each*
100% each*
100% each*
4

(Blocks 12-15)

 4 × 25%  2 × 50% over two rows 100% each*

*Blocks wrap and are displayed underneath each other

Responsive behavior - Size XL
Responsive behavior - Size XL
Responsive behavior - Size M
Responsive behavior - Size M
Responsive behavior - Size S
Responsive behavior - Size S

Sections with Horizontal Scrolling

The width of the horizontal scrolling area in different device contexts:

 

Blocks per section XL, L M S
3 – 5 40% 40% 90%
6 – 10 22.5% 40% 90%
Responsive behavior of a section with horizontal scrolling - Size L
Responsive behavior of a section with horizontal scrolling - Size L
Responsive behavior of a section with horizontal scrolling - Size M
Responsive behavior of a section with horizontal scrolling - Size M
Responsive behavior of a section with horizontal scrolling - Size S
Responsive behavior of a section with horizontal scrolling - Size S

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

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show multiple facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • You plan to use only one single tab.

Responsiveness

The icon tab bar stretches horizontally, which often exceeds the available width on small screens. It responds to limited space by offering a scrolling mechanism.

Responsiveness – Text tabs
Responsiveness – Text tabs
Responsiveness – Icon tabs
Responsiveness – Icon tabs

In addition to the responsive overflow behavior, the icon tab bar can be forced into compact mode or even react dynamically to the application’s global density setting. See the Tab Density section for details.

If there is not enough space to show all the tabs on the main tab bar, an overflow menu appears, containing all the remaining tabs that do not fit on the screen. By default, the overflow menu appears on the far right (see image “Responsiveness – Overflow on the far right”).

Another option is to display an overflow menu on both sides of the icon tab bar. The use of this overflow behavior depends on whether the order of the tabs is fixed or can be rearranged:

Responsiveness – Overflow on the far right
Responsiveness – Overflow on the far right

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters next to the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels do not become too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure that the UpperCase property is disabled and that you enter the labels in title case (for example: Approval Flow).

Types – Text-only without counters
Types – Text-only without counters
Types – Text-only with inline counters
Types – Text-only with inline counters

Counters and Text Tabs

If counters are used, set the property HeaderMode to “Inline” so the counters appear in brackets after the labels.

Do not use the old layout that shows the counters on top of the labels (Headermode = “Standard”).

Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Types – Icons with counters
Types – Icons with counters

Please note that starting with SAPUI5 version 1.40, you should only use the horizontal type of label (icon and label side by side).

If your labels get truncated, consider using shorter labels or text tabs (without icons), since text tabs cannot get truncated.

Types – Icons with counters and labels
Types – Icons with counters and labels
Types – Icon-only
Types – Icon-only

Tabs as Filters

If you build the tab bar as a filter, it can comprise two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 189 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Types – Filter
Types – Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the process steps, you can use the triple-chevron icon ( ) from the SAP icon font (technical name: process). Do not use the triple-chevron icon in the anchor bar of an object page.

If the process steps have a fixed order, set the property TabsOverflowMode to “StartAndEnd” to show an overflow menu on both sides and to keep the order of the tabs intact.

Types – Process
Types – Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Hierarchies

The tab bar supports hierarchies, allowing multiple tabs underneath one main tab. This way, you can group several tabs together, with the main tab acting as a headline.

Subtabs

The example on the right shows the main tab Notes with two subtabs, Internal and External, with no specific hierarchy except for their order.

Types – Subtabs
Types – Subtabs

Nested Tabs

Nesting allows deeper hierarchies with indentations to indicate the level of each tab.

By default, the property maxNestingLevel is “0” (zero). To enable nesting, adjust this value to the highest level of nesting that your app allows.

Types – Nested tabs
Types – Nested tabs

Behavior and Interaction

Clicking a Tab

To navigate through the views, the user clicks the tabs.

Optional behavior: If the user clicks a tab that is already open, the container collapses. It opens again when the user clicks any tab.

Use the expandable property to specify whether users can collapse the tab container (default = “true”):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the expandable property to “false”.

The expandable property controls the initial state of the container. Do not change the default state (“true”).

Changing the Order of Tabs

You can allow users to rearrange the tab order in a desktop environment (property: enableTabReordering). If this feature is enabled, users can drag and drop tabs to reorder them, either directly on the tab bar or inside the overflow menu.

It is also possible to drag and drop tabs from the tab bar to the overflow menu and vice versa.

If nesting is enabled (property maxNestingLevel > 0), users can choose the level at which they want to drop a tab.

Dragging a tab activates a visual indicator for positioning the tab. For example, dragging tab 8 on top of tab 5 makes tab 8 the child of the now highlighted tab 5 (see image 1).

If the user drags a tab between two other tabs, the indicator shows the level at which level the tab will be nested (see image 2).

Interaction - Tab nesting using drag and drop (1 of 2)
Interaction - Tab nesting using drag and drop (1 of 2)
Interaction - Tab nesting using drag and drop (2 of 2)
Interaction - Tab nesting using drag and drop (2 of 2)
Guidelines
Do not use this feature for:

  • Tabs as process steps:
    This ensures that consecutive steps do not get mixed up.
  • Anchor bar navigation:
    Sections that are represented in the anchor bar have a fixed order.

Styles

Tab Density

The default responsive design of the icon tab bar applies to both compact and cozy modes. However, in addition to this responsive behavior, the control can be forced into a compact mode, or even react dynamically to the application’s global density setting. This feature can be used to:

  • Save vertical space on the page (applies to both text and icon tabs)
  • Save horizontal space (icon tabs only; this is especially helpful when there are many tabs)
  • Generally use less space on mobile devices
  • Reduce noise when there are already more important visual elements on the screen (primarily icon tabs)

The property for the override is called tabDensityMode, which can be set to “Cozy”, “Compact”, or “Inherit”. “Cozy” is the default setting that renders the control in its regular dimensions. “Compact” reduces the control’s height and icon sizes (if applicable), even if there would be enough space for the cozy design. “Inherit” instructs the control to follow the global density mode defined for the application. For backward compatibility, the default setting is “Cozy”.

The following image shows some types of tabs with their default style (cozy, left) and the reduced density mode (compact, right).

Style – Tab density
Style – Tab density

Colors

The two different styles (round tabs and text only) are discussed in the Types section. In both cases, you can use semantic colors to give users additional orientation.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors. For more information, see How to Use Semantic Colors.

Developer Hint
To apply semantic colors to the icons and the text-only tabs, you can use the property sap.ui.core.IconColor.

Example

In the example below, one step in the process is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles – Colors
Styles – Colors

Badge

A tab can have an attention badge to indicate that new items were added to that tab. Only display a badge if new items are triggered from outside the app. Do not display a badge when users add new items themselves.

Icon tab with an attention badge
Icon tab with an attention badge

Badge in Default or Semantic State

You can add a badge to all types of icon tab bar.

The badge inherits the state of its tab (default state or semantic state):

  • For the default tab state, the default red badge is displayed.
  • If the tab has a semantic state, the badge inherits the semantic color for the current state.

Don’t mix tabs in the default state with tabs that have a semantic state.

Badge for the default state / semantic state

Badge Interaction

The badge becomes part of the tab. When the user selects a tab with a badge, the badge disappears. If a new item is added to the tab that is currently open, no badge is shown.

In addition, the badge inherits the interaction of its tab. For example, if a tab is moved using drag and drop, the attention badge moves with it.

Selecting a tab with a badge
Selecting a tab with a badge

Overflow Menu

If there isn’t enough space to show all the tabs on the main bar, an overflow menu appears on the right by default, containing all the remaining tabs. Depending on the use case, an overflow menu can also appear on both sides (for example, for process steps or anchor bar navigation).

A badge on the chevron icon   indicates that a tab within the overflow menu has received new items. The tab in question is indicated by a second badge on the item in the overflow menu.

Badge within overflow menu
Badge within overflow menu

Guidelines

Apply the styles as follows:

  • Icons only: Use this option if you have only 4-5 tabs that can be very clearly identified by their icon. If a short description is needed, use icons and labels.
  • Text only: Use this option if you have more than 4-5 tabs, or if there are no clear icons to represent the content. The text-only style also allows for longer labels. Set the property HeaderMode to “Inline”.
Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B. This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Form / Simple Form

Information
This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

Intro

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form in display-only mode
Form in display-only mode
Form in edit mode
Form in edit mode
Developer Hint
The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

The default settings of the control are not ideal for all possible use cases. Instead, applications can use one of the various layouts for the S, M, L and XL sizes.

Column Layout

The ColumnLayout control renders a form group in a column-based responsive way. Depending on its size, the group is divided into one or more columns.

  • XL – max. 6 columns
  • L – max. 3 columns
  • M – max. 2 columns
  • S – 1 column

For size XL, we recommend using the full 6 columns for large forms with a lot of content. This gives you greater flexibility when organizing the content and the form groups.​

To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns. The group elements are spread out into columns, depending on the number of group elements and their size.

Example:

  • 4 columns and 2 groups: each group will use 2 columns.
  • 3 columns and 2 groups: the larger one will use 2 columns, the smaller one 1 column.

The size of a group element will be determined by the number of visible elements assigned to it. If there are more groups than columns, every group uses only one column. So the last row of the form control will not be fully used. This will result in white space.

The form elements are spread out to the columns of a group arranged in a newspaper-like order. The position of the labels and fields depends on the size of the used column. If there is enough space, the labels are next to the fields, otherwise above the fields.

If you use the default form settings, each form group is displayed in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right side of the screen.

 

The examples show how forms with one and two form groups are displayed with and without layout balancing.

One form group with default arrangement
One form group with default arrangement
One form group with balanced column layout
One form group with balanced column layout
Two form groups with default arrangement
Two form groups with default arrangement
Two form groups with balanced column layout
Two form groups with balanced column layout

Responsive Grid Layout

The responsive grid layout is a form using a responsive grid. Depending on the available space, the groups are rendered in one or multiple columns, and the labels are rendered in the same row as the fields or above the fields. This behavior can be influenced by the properties of this layout control.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is the column layout, not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field ratio of 3:5:4
Form with a label-field ratio of 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form and simple form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S (12:12:0)
Form in size S (12:12:0)

Size M

Size M of the form and simple form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M (2:10:0)
Form in size M (2:10:0)

Size L

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

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

  • 4 grid columns of the responsive grid layout are used by the labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size L (4:8:0)
Form in size L (4:8:0)

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL (4:8:0)
Form in size XL (4:8:0)
Developer Hint
For forms and simple forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

Form with several groups (no form title)
Form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – Size M (4:7:1)
Form in a split screen – Size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – Size M (3:5:4)
Form in full screen – Size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – Size M (4:8:0)
Form with long labels and fields – Size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – Size M (12:12:0)
Form with several form groups (two columns) – Size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – Size L (3:5:4)
Form with a single form group (one column) – Size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – Size L (12:12:0)
Form with several form groups (two columns) – Size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – Size XL (3:5:4)
Form with a single form group (one column) – Size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – Size XL (4:8:0)
Form with an empty column – Size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with single group in a column layout - Size XL - (12:12:0)
Form with single group in a column layout - Size XL - (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – Size XL (4:8:0)
Form with multiple form groups (two columns) – Size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – Size XL (12:12:0)
Form with two form groups (three columns) – Size XL (12:12:0)
Form with three form groups (three columns) – Size XL (12:12:0)
Form with three form groups (three columns) – Size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

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

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user’s name before asking them for their address.
  • Group related information by using form and group titles.
  • Use Column layout instead of Responsive Grid layout, if possible.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Label

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is to make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

  • A label is not a help text. Give each field a meaningful label. Make labels succinct, short and descriptive.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property, and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the style sheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)

Label Alignment

  • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
  • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
Information
The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

Empty State Indicator

If the form field doesn’t have a value, show an empty state indicator in display mode. This helps the user to better scan the form and perceive the field label and empty content as one unit.

Developer Hint
The empty indicator does not show by default. You need to activate it for the respective text (property: emptyIndicatorMode).
Empty state indicator
Empty state indicator

Unit of Measurement

You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

Unit of measurement
Unit of measurement

Amount Alignment

When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page (for example, if the user selects a list item in a list-detail layout and then clicks the the Back or Home button). For details about how the message is delivered and what text you can use, see Message Handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

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.

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

Toolbar

The form supports actions on form toolbar level as well as on group header level. Application development teams can add actions such as ‘Edit’, ‘Save’ or ‘Cancel’. If there is an action that only applies to the specific group on group level, it can only be added on the group header level of the specific group.

Expanded/ Collapsed Form

The form supports expand / collapse buttons on a per-group level. However, we recommend avoiding the usage of expand / collapse behavior on a form.

Resources

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

Elements and Controls

Implementation

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show multiple facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • You plan to use only one single tab.

Responsiveness

The icon tab bar stretches horizontally, which often exceeds the available width on small screens. It responds to limited space by offering a scrolling mechanism.

Responsiveness – Text tabs
Responsiveness – Text tabs
Responsiveness – Icon tabs
Responsiveness – Icon tabs

In addition to the responsive overflow behavior, the icon tab bar can be forced into compact mode or even react dynamically to the application’s global density setting. See the Tab Density section for details.

If there is not enough space to show all the tabs on the main tab bar, an overflow menu appears, containing all the remaining tabs that do not fit on the screen. By default, the overflow menu appears on the far right (see image “Responsiveness – Overflow on the far right”).

Another option is to display an overflow menu on both sides of the icon tab bar. The use of this overflow behavior depends on whether the order of the tabs is fixed or can be rearranged:

Responsiveness – Overflow on the far right
Responsiveness – Overflow on the far right

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters next to the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels do not become too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure that the UpperCase property is disabled and that you enter the labels in title case (for example: Approval Flow).

Types – Text-only without counters
Types – Text-only without counters
Types – Text-only with inline counters
Types – Text-only with inline counters

Counters and Text Tabs

If counters are used, set the property HeaderMode to “Inline” so the counters appear in brackets after the labels.

Do not use the old layout that shows the counters on top of the labels (Headermode = “Standard”).

Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Types – Icons with counters
Types – Icons with counters

Please note that starting with SAPUI5 version 1.40, you should only use the horizontal type of label (icon and label side by side).

If your labels get truncated, consider using shorter labels or text tabs (without icons), since text tabs cannot get truncated.

Types – Icons with counters and labels
Types – Icons with counters and labels
Types – Icon-only
Types – Icon-only

Tabs as Filters

If you build the tab bar as a filter, it can comprise two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 189 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Types – Filter
Types – Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the process steps, you can use the triple-chevron icon ( ) from the SAP icon font (technical name: process). Do not use the triple-chevron icon in the anchor bar of an object page.

If the process steps have a fixed order, set the property TabsOverflowMode to “StartAndEnd” to show an overflow menu on both sides and to keep the order of the tabs intact.

Types – Process
Types – Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Hierarchies

The tab bar supports hierarchies, allowing multiple tabs underneath one main tab. This way, you can group several tabs together, with the main tab acting as a headline.

Subtabs

The example on the right shows the main tab Notes with two subtabs, Internal and External, with no specific hierarchy except for their order.

Types – Subtabs
Types – Subtabs

Nested Tabs

Nesting allows deeper hierarchies with indentations to indicate the level of each tab.

By default, the property maxNestingLevel is “0” (zero). To enable nesting, adjust this value to the highest level of nesting that your app allows.

Types – Nested tabs
Types – Nested tabs

Behavior and Interaction

Clicking a Tab

To navigate through the views, the user clicks the tabs.

Optional behavior: If the user clicks a tab that is already open, the container collapses. It opens again when the user clicks any tab.

Use the expandable property to specify whether users can collapse the tab container (default = “true”):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the expandable property to “false”.

The expandable property controls the initial state of the container. Do not change the default state (“true”).

Changing the Order of Tabs

You can allow users to rearrange the tab order in a desktop environment (property: enableTabReordering). If this feature is enabled, users can drag and drop tabs to reorder them, either directly on the tab bar or inside the overflow menu.

It is also possible to drag and drop tabs from the tab bar to the overflow menu and vice versa.

If nesting is enabled (property maxNestingLevel > 0), users can choose the level at which they want to drop a tab.

Dragging a tab activates a visual indicator for positioning the tab. For example, dragging tab 8 on top of tab 5 makes tab 8 the child of the now highlighted tab 5 (see image 1).

If the user drags a tab between two other tabs, the indicator shows the level at which level the tab will be nested (see image 2).

Interaction - Tab nesting using drag and drop (1 of 2)
Interaction - Tab nesting using drag and drop (1 of 2)
Interaction - Tab nesting using drag and drop (2 of 2)
Interaction - Tab nesting using drag and drop (2 of 2)
Guidelines
Do not use this feature for:

  • Tabs as process steps:
    This ensures that consecutive steps do not get mixed up.
  • Anchor bar navigation:
    Sections that are represented in the anchor bar have a fixed order.

Styles

Tab Density

The default responsive design of the icon tab bar applies to both compact and cozy modes. However, in addition to this responsive behavior, the control can be forced into a compact mode, or even react dynamically to the application’s global density setting. This feature can be used to:

  • Save vertical space on the page (applies to both text and icon tabs)
  • Save horizontal space (icon tabs only; this is especially helpful when there are many tabs)
  • Generally use less space on mobile devices
  • Reduce noise when there are already more important visual elements on the screen (primarily icon tabs)

The property for the override is called tabDensityMode, which can be set to “Cozy”, “Compact”, or “Inherit”. “Cozy” is the default setting that renders the control in its regular dimensions. “Compact” reduces the control’s height and icon sizes (if applicable), even if there would be enough space for the cozy design. “Inherit” instructs the control to follow the global density mode defined for the application. For backward compatibility, the default setting is “Cozy”.

The following image shows some types of tabs with their default style (cozy, left) and the reduced density mode (compact, right).

Style – Tab density
Style – Tab density

Colors

The two different styles (round tabs and text only) are discussed in the Types section. In both cases, you can use semantic colors to give users additional orientation.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors. For more information, see How to Use Semantic Colors.

Developer Hint
To apply semantic colors to the icons and the text-only tabs, you can use the property sap.ui.core.IconColor.

Example

In the example below, one step in the process is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles – Colors
Styles – Colors

Badge

A tab can have an attention badge to indicate that new items were added to that tab. Only display a badge if new items are triggered from outside the app. Do not display a badge when users add new items themselves.

Icon tab with an attention badge
Icon tab with an attention badge

Badge in Default or Semantic State

You can add a badge to all types of icon tab bar.

The badge inherits the state of its tab (default state or semantic state):

  • For the default tab state, the default red badge is displayed.
  • If the tab has a semantic state, the badge inherits the semantic color for the current state.

Don’t mix tabs in the default state with tabs that have a semantic state.

Badge for the default state / semantic state

Badge Interaction

The badge becomes part of the active area of the tab. When the user activates a tab with a badge, the badge disappears. If a new item is added to the tab that is currently open, no badge is shown.

In addition, the badge inherits the interaction of its tab. For example, if a tab is moved using drag and drop, the attention badge moves with it.

Interaction example: Activating a tab with a badge
Interaction example: Activating a tab with a badge

Overflow Menu

If there isn’t enough space to show all the tabs on the main bar, an overflow menu appears on the right by default, containing all the remaining tabs. Depending on the use case, an overflow menu can also appear on both sides (for example, for process steps or anchor bar navigation).

A badge on the chevron icon   indicates that a tab within the overflow menu has received new items. The tab in question is indicated by a second badge on the item in the overflow menu.

Badge within overflow menu
Badge within overflow menu

Guidelines

Apply the styles as follows:

  • Icons only: Use this option if you have only 4-5 tabs that can be very clearly identified by their icon. If a short description is needed, use icons and labels.
  • Text only: Use this option if you have more than 4-5 tabs, or if there are no clear icons to represent the content. The text-only style also allows for longer labels. Set the property HeaderMode to “Inline”.
Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B. This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Card

Information
Integration cards are already available in SAPUI5, but cannot currently be consumed in the SAP S/4HANA environments (on premise and cloud).

Intro

A card represents an app or page. It can be used to launch the app or navigate to the page content. Integration cards are a way of making application content available to end users in a consistent manner.

Integration cards are similar to the cards on the overview page. However, unlike the overview page cards, integration cards can be used in different host environments.

A card can show details about a single app or page, or contain related information from multiple sources. An app or page can also be represented by several cards, which each focus on a different aspect of the content.

Card examples
Card examples

When to Use

You can offer cards on the SAP Fiori launchpad or embed them in other controls.

Offer a card if:

  • You want to give users easy access to an app or page that is relevant for a business task.
  • You want to show a KPI or a preview of the most important content for the task.
  • You want to let users complete a simple action right away, without navigating to the underlying app.

Card Anatomy

A card comprises a header and a content area, which are separated by a divider line. Both components are inside a card container, which includes the background and the border.

Header

The header shows what the card is about. There are two variants: the default header and the numeric header.

Card structure
Card structure

Default Header

The default header shows the basic information about the card and has the following components:

  1. The title is mandatory and represents the “point of view” of the card. Titles longer than three lines are truncated with an ellipsis (…).
  2. Optional: You can use a subtitle to qualify the title or explain the context. Subtitles that exceed two lines are truncated.
  3. Optional: You can use an avatar to provide a visual hint on the card header (for example, an image, icon, or initials).
  4. If the content area contains multiple items, a counter is added to the header. It shows how many items are visible on the card in relation to the total number of relevant items (for example, “6 of 12”).
Default header
Default header

Numeric Header

Use the numeric header if you need to display numeric information.

  1. Mandatory title
  2. You can add a subtitle with additional qualifying information (optional).
  3. If you specify a currency or unit of measurement, it also appears in the subtitle row. If you provide both a subtitle and a unit of measurement, the display format is: <subtitle text> | <unit of measurement>.
  4. In additional to the general information, you can configure the visualization for a numeric value, such as a KPI.
  5. If required, you can also show up to two additional indicators that relate to the main KPI.
  6. If required, you can display more information about the numeric value directly below it (for example, the period for which a KPI applies).
Numeric header
Numeric header
Guidelines
Ensure that the card title is short, clear and precise.

Provide all the information required to interpret the numeric value (specific description, currency or unit of measurement, relevant period).

  • For currencies and standard units of measurement, use the dedicated unitOfMeasurement property. The unit then appears consistently in the subtitle line. If the value is a simple count (such as the number of open tasks), a precise title/subtitle text is usually sufficient.
  • If the value applies to a period, use the footer area (5) to specify the period.

Content Area

The content area is reserved for showing information from the underlying source(s). Cards can represent different types of content, with several visualization options. This depends on which card type is used.

Guidelines
In the card content area, show the most relevant data for the task at hand.

Card Types

The card type defines how content is presented (for example, as a list or table). The embedded controls govern the layout, navigation, and interaction in the card content area.

The following card types are available:

List Card

The list card can display multiple list items of various types.

Schematic example of a list card
Schematic example of a list card

Analytical Card

The analytical card visualizes analytics data. It can contain a line chart, bar chart, or donut chart.

Schematic example of an analytical card
Schematic example of an analytical card

Table Card

The table card displays multiple items in a table view.

Schematic example of a table card
Schematic example of a table card

Object Card

You can use this card type to display information about an object in groups. Each group can contain as many items as needed.

Schematic example of an object card
Schematic example of an object card

Timeline Card

The timeline card displays time-related content in chronological order.

Schematic example of a timeline card
Schematic example of a timeline card

Calendar Card

The calendar card shows the schedule for a single entity (typically a person) for a selected day.

Schematic example of a calendar card
Schematic example of a calendar card

Component Card

The component card allows you to display a SAPUI5 component as content. This gives you significant flexibility in configuring the content.

Behavior and Interaction

Card Header

The whole header is clickable and is the navigation area for opening the underlying source. Clicking the header opens the app or page that relates to the card.

Card Content

The content area can have several click areas with different purposes. They depend on the control used and the structure of the content.

Guidelines
Always provide meaningful navigation targets. Ensure that the navigation target supports the information flow that starts on the card.
Card interaction
Card interaction

Responsiveness

The responsive behavior for integration cards depends on the container control of the host environment (for example, SAP Fiori launchpad). The size of the card adapts dynamically to the size of the container.

Top Tips

  • Cards introduce users to the content in the underlying source. Make sure that your card focuses on the most relevant content.
  • Use cards if supportive visualizations and meaningful navigations are helpful for users.
  • Don’t use individual branding.
  • Avoid unnecessary white space on the card.

Related Links

Elements and Controls

Implementation

Form / Simple Form

Information
This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

Intro

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display- only mode
Form control in display- only mode
Form in edit mode
Form in edit mode
Developer Hint
The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

The default settings of the control are not ideal for all possible use cases. Instead, applications can use one of the various layouts for the S, M, L and XL sizes.

Column Layout

The ColumnLayout control renders a form group in a column-based responsive way. Depending on its size, the group is divided into one or more columns.

  • XL – max. 6 columns
  • L – max. 3 columns
  • M – max. 2 columns
  • S – 1 column

For size XL, we recommend using the full 6 columns for large forms with a lot of content. This gives you greater flexibility when organizing the content and the form groups.​

To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns. The group elements are spread out into columns, depending on the number of group elements and their size.

Example:

  • 4 columns and 2 groups: each group will use 2 columns.
  • 3 columns and 2 groups: the larger one will use 2 columns, the smaller one 1 column.

The size of a group element will be determined by the number of visible elements assigned to it. If there are more groups than columns, every group uses only one column. So the last row of the form control will not be fully used. This will result in white space.

The form elements are spread out to the columns of a group arranged in a newspaper-like order. The position of the labels and fields depends on the size of the used column. If there is enough space, the labels are next to the fields, otherwise above the fields.

If you use the default form settings, each form group is displayed in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right side of the screen.

 

The examples show how forms with one and two form groups are displayed with and without layout balancing.

One form group with default arrangement
One form group with default arrangement
One form group with balanced column layout
One form group with balanced column layout
Two form groups with default arrangement
Two form groups with default arrangement
Two form groups with balanced column layout
Two form groups with balanced column layout

Responsive Grid Layout

The responsive grid layout is a form using a responsive grid. Depending on the available space, the groups are rendered in one or multiple columns, and the labels are rendered in the same row as the fields or above the fields. This behavior can be influenced by the properties of this layout control.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is the column layout, not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field ratio of 3:5:4
Form with a label-field ratio of 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form and simple form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form and simple form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms and simple forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

Form with several groups (no form title)
Form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – Size M (4:7:1)
Form in a split screen – Size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – Size M (3:5:4)
Form in full screen – Size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – Size M (4:8:0)
Form with long labels and fields – Size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – Size M (12:12:0)
Form with several form groups (two columns) – Size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – Size L (3:5:4)
Form with a single form group (one column) – Size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – Size L (12:12:0)
Form with several form groups (two columns) – Size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – Size XL (3:5:4)
Form with a single form group (one column) – Size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – Size XL (4:8:0)
Form with an empty column – Size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with single group in a column layout - Size XL - (12:12:0)
Form with single group in a column layout - Size XL - (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – Size XL (4:8:0)
Form with multiple form groups (two columns) – Size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – Size XL (12:12:0)
Form with two form groups (three columns) – Size XL (12:12:0)
Form with three form groups (three columns) – Size XL (12:12:0)
Form with three form groups (three columns) – Size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

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

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user’s name before asking them for their address.
  • Group related information by using form and group titles.
  • Use Column layout instead of Responsive Grid layout, if possible.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Label

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is to make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

  • A label is not a help text. Give each field a meaningful label. Make labels succinct, short and descriptive.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property, and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the style sheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)

Label Alignment

  • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
  • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
Information
The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

Empty State Indicator

If the form field doesn’t have a value, show an empty state indicator in display mode. This helps the user to better scan the form and perceive the field label and empty content as one unit.

Developer Hint
The empty indicator does not show by default. You need to activate it for the respective text (property: emptyIndicatorMode).
Empty state indicator
Empty state indicator

Unit of Measurement

You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

Unit of measurement
Unit of measurement

Amount Alignment

When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

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.

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

Toolbar

The form supports actions on form toolbar level as well as on group header level. Application development teams can add actions such as ‘Edit’, ‘Save’ or ‘Cancel’. If there is an action that only applies to the specific group on group level, it can only be added on the group header level of the specific group.

Expanded/ Collapsed Form

The form supports expand / collapse buttons on a per-group level. However, we recommend avoiding the usage of expand / collapse behavior on a form.

Resources

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

Elements and Controls

Implementation

Scroll Container

The scroll container is an empty area that can be filled with content, such as other UI elements. The user can scroll through the content.

When to Use

Use a scroll container if:

  • You want to provide a content area that would otherwise be partly or completely covered or hidden.

Do not use a scroll container if:

  • A page uses a full screen element that can handle vertical scrolling.
  • You are using other controls that come with their own scroll container, such as a dialog, timeline, or panel.
  • You plan to nest different scroll containers that scroll in the same direction.
  • You plan to have several scroll containers with different scroll directions (horizontally and vertically) on one page. This may lead to confusion about when to use which scrolling direction and how it all fits together.

Behavior and Interaction

The scroll container displays a scrollbar on the side for vertical scrolling and on the bottom for horizontal scrolling.

In addition, the scroll container is also focusable.

Vertical scrolling in a list
Vertical scrolling in a list

Responsiveness

The scroll container is responsive and adapts to the screen size. By default, the width consumes the complete available width and the height reflects the height of the content. You can also set a fixed width or height. Always use responsive controls for the content, so that they also adapt to the available width and height.

Guidelines
If you are only using horizontal scrolling, do not set the height, or ensure that the height of the container always exceeds the height of the content.

Related Links

Elements and Controls

Implementation

Smart Form

The smart form control creates a form. If used with smart fields, the smart form provides both read-only and editable views, and OData annotations for the smart fields are taken into account. The smart form also provides a toolbar with a title.

When to Use

Use the smart form if:

  • You use an OData service for your app (OData version 2 only).
  • You are using only (or primarily) smart fields inside your form. In this case, the smart form is faster to implement.

Do not use the smart form if:

Components

The smart form consists of a toolbar and a form.

Toolbar

The following options are provided:

  1. Expand/collapse button
  2. Title
  3. App-specific actions

Expand/Collapse Button

The expand/collapse button is optional (properties: expandable,
expanded). It shows or hides the form.

Expanded smart form
Expanded smart form
Collapsed smart form
Collapsed smart form
Guidelines

  • Do not use the expand/collapse button in object pages.
  • Even in other places, it is not usually recommended.

Title

The title is optional (property: title).

App-Specific Actions

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

Guidelines
For custom actions, follow the guidelines for object handling.
Developer Hint
The smart form can add its title to the custom toolbar.

Form

The form consists of form groups (sap.ui.comp.smartform.Group) and a layout.

Form Groups

Each form group comes with:

  • A title
  • One or several form elements and/or semantic form elements

Form elements (sap.ui.comp.smartform.GroupElement) consist of a label and one or several UI elements. If smart fields are used, the label is automatically provided by the corresponding metadata. If more than one smart field is used, define which label to display (GroupElement, property: elementForLabel).

The semantic form element (sap.ui.comp.smartform.SemanticGroupSlement) provides additional support when more than one control is attached to a single label. In display mode, the corresponding texts are displayed as a single value and therefore use less space. You can define a delimiter, which is shown between the fields.

A semantic form element in edit mode
A semantic form element in edit mode
The same semantic form element in display mode
The same semantic form element in display mode
Guidelines
When using more than one control in a form element, consider the semantic form element. In most cases, it will be the better choice.
Developer Hint

  • Ideally, use only smart fields.
  • If this is not possible, use only controls that implement theIFormContent interface . Other controls could damage the visual layout, keyboard support, and screen reader support.

Layout

The layout defines how the form groups and form elements are placed on the screen, depending on the available width (aggregation: layout). There are two layout options: column layout and responsive grid layout.

Guidelines

Behavior and Interaction

Display and Edit Mode

In display mode, the line height for each row is reduced (property: editable). This results in less white space between two lines of text. This setting is passed to all smart fields inside the smart form, which then also switch automatically.

Developer Hint
Controls other than the smart field need to be adapted manually.

Validation

The smart form offers two validation modes: standard and asynchronous (property: validationMode). The standard validation mode works only for smart fields and only with synchronous validation.

Developer Hint
Always use the asynchronous mode: it works for all form elements, not only for smart fields.

Responsiveness

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

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

Example

Smart form in edit mode
Smart form in edit mode
The same smart form in display mode
The same smart form in display mode

Top Tips

Properties

The following properties are available for sap.ui.comp.smartform.SmartForm:

  • The property: checkButton adds a button labeled Check to the toolbar. The button triggers front-end validation on available smart fields. Do not use it. Follow the guidelines for form field validation instead.
  • The property: editToggable adds an icon-only button to the toolbar, which switches the editable property. Do not use it. Follow the guidelines for object handling instead.
  • The property: entityType is used for key user adaptations.
  • The property: flexEnabled is used for key user adaptations.
  • The property: horizontalLayoutGroupElementMinWidth only works with the horizontal layout, which is deprecated. Do not use it. Use the column layout instead.
  • The property: ignoredFields is used for key user adaptations.
  • The property: importance hides all smart fields with lower importance. Do not use it.
  • The property: useHorizontalLayout only works with the horizontal layout, which is deprecated. Use the column layout instead.

The following properties are available for sap.ui.comp.smartform.Group:

  • The property: horizontalLayoutGroupElementMinWidth only works with the horizontal layout, which is deprecated. Use the column layout instead.
  • The property: label is deprecated. Use the aggregation: title instead.
  • The property: useHorizontalLayout only works with the horizontal layout, which is deprecated. Use the column layout instead.
  • The aggregation: layout is deprecated. Use the aggregation: layoutData instead.

Related Links

Elements and Controls

Implementation

Form / Simple Form

Information
This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

Intro

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display- only mode
Form control in display- only mode
Form in edit mode
Form in edit mode
Developer Hint
The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

The default settings of the control are not ideal for all possible use cases. Instead, applications can use one of the various layouts for the S, M, L and XL sizes.

Column Layout

The  ColumnLayout control renders a form group in a column-based responsive way. Depending on its size, the group is divided into one or more columns.

  • XL – max. 4 columns
  • L – max. 3 columns
  • M – max. 2 columns
  • S – 1 column

To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns. The group elements are spread out into columns, depending on the number of group elements and their size.

Example:

  • 4 columns and 2 groups: each group will use 2 columns.
  • 3 columns and 2 groups: the larger one will use 2 columns, the smaller one 1 column.

The size of a group element will be determined by the number of visible elements assigned to it. If there are more groups than columns, every group uses only one column. So the last row of the form control will not be fully used. This will result in white space.

The form elements are spread out to the columns of a group arranged in a newspaper-like order. The position of the labels and fields depends on the size of the used column. If there is enough space, the labels are next to the fields, otherwise above the fields.

If you use the default form settings, each form group is displayed in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right side of the screen.

 

The examples show how forms with one and two form groups are displayed with and without layout balancing.

One form group with default arrangement
One form group with default arrangement
One form group with balanced column layout
One form group with balanced column layout
Two form groups with default arrangement
Two form groups with default arrangement
Two form groups with balanced column layout
Two form groups with balanced column layout

Responsive Grid Layout

The responsive grid layout is a form using a responsive grid. Depending on the available space, the groups are rendered in one or multiple columns, and the labels are rendered in the same row as the fields or above the fields. This behavior can be influenced by the properties of this layout control.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is the column layout, not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field ratio of 3:5:4
Form with a label-field ratio of 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form and simple form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form and simple form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms and simple forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – Size M (4:7:1)
Form in a split screen – Size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – Size M (3:5:4)
Form in full screen – Size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – Size M (4:8:0)
Form with long labels and fields – Size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – Size M (12:12:0)
Form with several form groups (two columns) – Size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – Size L (3:5:4)
Form with a single form group (one column) – Size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – Size L (12:12:0)
Form with several form groups (two columns) – Size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – Size XL (3:5:4)
Form with a single form group (one column) – Size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – Size XL (4:8:0)
Form with an empty column – Size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with single group in a column layout - Size XL - (12:12:0)
Form with single group in a column layout - Size XL - (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – Size XL (4:8:0)
Form with multiple form groups (two columns) – Size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – Size XL (12:12:0)
Form with two form groups (three columns) – Size XL (12:12:0)
Form with three form groups (three columns) – Size XL (12:12:0)
Form with three form groups (three columns) – Size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

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

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user’s name before asking them for their address.
  • Group related information by using form and group titles.
  • Use Column layout instead of Responsive Grid layout, if possible.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • If the form field doesn’t have a value, add an empty state indicator in the display-only mode. This is not a default property, so you will have to add it specifically.
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Label

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is to make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

  • A label is not a help text. Give each field a meaningful label. Make labels succinct, short and descriptive.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property, and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the style sheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)

Label Alignment

  • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
  • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
Information
The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

Unit of Measurement

You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

Unit of Measurement
Unit of Measurement

Amount Alignment

When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

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.

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

Toolbar

The form supports actions on form toolbar level as well as on group header level. Application development teams can add actions such as ‘Edit’, ‘Save’ or ‘Cancel’. If there is an action that only applies to the specific group on group level, it can only be added on the group header level of the specific group.

Expanded/ Collapsed Form

The form supports expand / collapse buttons on a per-group level. However, we recommend avoiding the usage of expand / collapse behavior on a form.

Resources

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

Elements and Controls

Implementation

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show multiple facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • You plan to use only one single tab.

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Responsiveness – Text tabs
Responsiveness – Text tabs
Responsiveness – Icon tabs
Responsiveness – Icon tabs

In addition to the responsive overflow behavior, the icon tab bar can be forced into compact mode or even react dynamically to the application’s global density setting. See the Tab Density section for details.

When the screen space does not allow to show all tabs on the main tab bar, an overflow appears on the far right, containing all remaining tabs that do not fit on the screen.

Responsiveness – Overflow
Responsiveness – Overflow

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters next to the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels do not become too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure that the UpperCase property is disabled and that you enter the labels in title case (for example: Approval Flow).

Types – Text-only without counters
Types – Text-only without counters
Types – Text-only with inline counters
Types – Text-only with inline counters

Counters and Text Tabs

If counters are used, set the property HeaderMode to “Inline” so the counters appear in brackets after the labels.

Do not use the old layout that shows the counters on top of the labels (Headermode = “Standard”).

Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Types – Icons with counters
Types – Icons with counters

Please note that starting with SAPUI5 version 1.40, you should only use the horizontal type of label (icon and label side by side).

If your labels get truncated, consider using shorter labels or text tabs (without icons), since text tabs cannot get truncated.

Types – Icons with counters and labels
Types – Icons with counters and labels
Types – Icon-only
Types – Icon-only

Tabs as Filters

If you build the tab bar as a filter, it can comprise two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 189 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Types – Filter
Types – Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Types – Process
Types – Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Warning
The overflow behavior changed in SAPUI5 version 1.80. Tabs from the overflow are shown on the main tab bar as long as they are selected. This may disrupt the order of your process and give the impression of a false step order. We are working on a fix for this issue.

Hierarchies

The tab bar supports hierarchies, allowing multiple tabs underneath one main tab. This way, you can group several tabs together, with the main tab acting as a headline.

Subtabs

The example on the right shows the main tab Notes with two subtabs, Internal and External, with no specific hierarchy except for their order.

Types – Subtabs
Types – Subtabs

Nested Tabs

Nesting allows deeper hierarchies with indentations to indicate the level of each tab.

By default, the property maxNestingLevel is “0” (zero). To enable nesting, adjust this value to the highest level of nesting that your app allows.

Types – Nested tabs
Types – Nested tabs

Behavior and Interaction

Clicking a Tab

To navigate through the views, the user clicks the tabs.

Optional behavior: If the user clicks a tab that is already open, the container collapses. It opens again when the user clicks any tab.

Use the expandable property to specify whether users can collapse the tab container (default = “true”):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the expandable property to “false”.

The expandable property controls the initial state of the container. Do not change the default state (“true”).

Changing the Order of Tabs

You can allow users to rearrange the tab order in a desktop environment (property: enableTabReordering). If this feature is enabled, users can drag and drop tabs to reorder them, either directly on the tab bar or inside the overflow menu.

It is also possible to drag and drop tabs from the tab bar to the overflow menu and vice versa.

If nesting is enabled (property maxNestingLevel > 0), users can choose the level at which they want to drop a tab.

Dragging a tab activates a visual indicator for positioning the tab. For example, dragging tab 8 on top of tab 5 makes tab 8 the child of the now highlighted tab 5 (see image 1).

If the user drags a tab between two other tabs, the indicator shows the level at which level the tab will be nested (see image 2).

Interaction - Tab nesting using drag and drop (1 of 2)
Interaction - Tab nesting using drag and drop (1 of 2)
Interaction - Tab nesting using drag and drop (2 of 2)
Interaction - Tab nesting using drag and drop (2 of 2)
Information
Do not use this feature for tabs as process steps to ensure that consecutive steps do not get mixed up.

Styles

Tab Density

The default responsive design of the icon tab bar applies to both compact and cozy modes. However, in addition to this responsive behavior, the control can be forced into a compact mode, or even react dynamically to the application’s global density setting. This feature can be used to:

  • Save vertical space on the page (applies to both text and icon tabs)
  • Save horizontal space (icon tabs only; this is especially helpful when there are many tabs)
  • Generally use less space on mobile devices
  • Reduce noise when there are already more important visual elements on the screen (primarily icon tabs)

The property for the override is called tabDensityMode, which can be set to “Cozy”, “Compact”, or “Inherit”. “Cozy” is the default setting that renders the control in its regular dimensions. “Compact” reduces the control’s height and icon sizes (if applicable), even if there would be enough space for the cozy design. “Inherit” instructs the control to follow the global density mode defined for the application. For backward compatibility, the default setting is “Cozy”.

The following image shows some types of tabs with their default style (cozy, left) and the reduced density mode (compact, right).

Style – Tab density
Style – Tab density

Colors

The two different styles (round tabs and text only) are discussed in the Types section. In both cases, you can use semantic colors to give users additional orientation.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors. For more information, see How to Use Semantic Colors.

Developer Hint
To apply semantic colors to the icons and the text-only tabs, you can use the property sap.ui.core.IconColor.

Example

In the example below, one step in the process is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles – Colors
Styles – Colors

Badge

A tab can have an attention badge to indicate that new items were added to that tab. Only display a badge if new items are triggered from outside the app. Do not display a badge when users add new items themselves.

Icon tab with an attention badge
Icon tab with an attention badge

Badge in Default or Semantic State

You can add a badge to all types of icon tab bar.

The badge inherits the state of its tab (default state or semantic state):

  • For the default tab state, the default red badge is displayed.
  • If the tab has a semantic state, the badge inherits the semantic color for the current state.

Don’t mix tabs in the default state with tabs that have a semantic state.

Badge for the default state / semantic state

Badge Interaction

The badge becomes part of the active area of the tab. When the user activates a tab with a badge, the badge disappears. If a new item is added to the tab that is currently open, no badge is shown.

In addition, the badge inherits the interaction of its tab. For example, if a tab is moved using drag and drop, the attention badge moves with it.

Interaction example: Activating a tab with a badge
Interaction example: Activating a tab with a badge

Overflow Menu

If there isn’t enough space to show all the tabs on the main bar, an overflow menu appears on the right, containing all the remaining tabs. A badge on the chevron icon   indicates that a tab within the overflow menu received new items. The tab in question is indicated by a second badge on the item in the overflow menu.

Badge within overflow menu
Badge within overflow menu

Guidelines

Apply the styles as follows:

  • Icons only: Use this option if you have only 4-5 tabs that can be very clearly identified by their icon. If a short description is needed, use icons and labels.
  • Text only: Use this option if you have more than 4-5 tabs, or if there are no clear icons to represent the content. The text-only style also allows for longer labels. Set the property HeaderMode to “Inline”.
Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B. This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Block Layout

Information

This layout has been designed specifically for the tool landscape for the SAP Cloud Platform. It is not intended for use in regular SAP Fiori applications. 

Intro

The block layout is used to display content in a section-based manner. It features horizontal and vertical subdivisions and full-width banners seen frequently in contemporary web design. Background colors are attached directly to these areas within the layout. Also, special full-width sections of the block layout enable horizontal scrolling through a set of areas.

General page structure of a tool using the block layout
General page structure of a tool using the block layout

Usage

Use the block layout if:

  • You want to display section-based content. Place elements next to each other to indicate a content relationship.

Do not use the block layout if:

  • You want to display properties or features of one content item. Use the object page floorplan instead.
  • You want to display KPIs in the dashboard-variant. Use the overview page or a layout using cards instead.

Block layout case examples include landing pages and catalog-like pages.

In landing pages, the block layout may serve as a banner-like presentation of illustrative icons with associated text. By placing pictorial and textual elements side by side in different areas, a content relationship is established. In catalog-like layouts, the block layout serves as a flexible container for diverging content, such as headings, explanatory texts, code snippets, remarks, and examples.

It is also possible to have clickable blocks with their own hover and pressed states.

Layout

The block layout is divided into horizontal sections, which take on the full width of the available screen real estate. Their screen height is determined by their inner content, which prevents vertical scrolling.

If needed, the width of sections can also be set to the following predefined ratios (for the sizes XL, L and M):

  • 1 block: 100%
  • 2 blocks:
    • 50% and 50% or
    • 75% and 25% or
    • 25% and 75%
  • 3 blocks:
    • 3 × 33% or
    • 2 × 25% and 50% or
    • 50% and 2 × 25% or
    • 25% and 50% and 25%
  • 4 blocks: 4 × 25%

Block layouts can also contain sections that allow horizontal scrolling. These sections always have a width of 100%.

Schematic block layout
Schematic block layout
Schematic block layout with a section scrolling horizontally
Schematic block layout with a section scrolling horizontally

Components

Block layout components
Block layout components

1 – Section

1a – Section Title

2 – Block

2a – Block Title – can be text or a link.

2b – Block Body – can contain text or other controls.

Guidelines

  • Links within a block must lead to areas outside of the block. In addition, controls must update only their own containers.
  • Usage of disabled, emphasized or subtle links as block titles is not recommended. Dark background designs, for example when using the Accent variant, are not fully supported with regards to accessibility when used with links as titles.

Types

There are four types of block layouts:

  1. Default: This layout does not use any background colors.
  2. Dashboard: This layout type uses white blocks with spacing around them, making each block look like a card.
  3. Light: Areas use predefined colors found in the SAP Fiori 3 Quartz Light theme. These colors follow a specific order that is defined in the control. If there are more than six areas, the background colors start over beginning with the initial color.
  4. Accent: Each row contains a range of colors derived from one accent color, and these colors are used alternately. If required by the control, you can display multiple gray blocks: the different shades of gray will then be displayed alternately, beginning with the initial color.

Light Color Set

For the Light variant, use colors as follows:

  • block color A for the section title block.
  • block colors B, C, D, E, F and G for the blocks, one after another.
  • block color H for the footer.
Color set for the
Color set for the "Light" block layout type

Accent Color Sets

Row (Section) Color Sets

For the Accent variant of the block layout, you can use a different color set for each row (sap.ui.layout.BlockLayoutRow, property:rowColorSet). This enables different starting colors for the row coloring, and prevents color coalescence in the responsive behavior of the block layout.

Cell (Block) Colors

There are 10 predefined color sets that you can use as accent variants, each with 6 different shades.

To change the background of a particular block, set the desired color set (sap.ui.layout.BlockLayoutCell, property: backgroundColorSet) and color shade (sap.ui.layout.BlockLayoutCell, property: backgroundColorShade) accordingly.

Color set 1, with shades A to F
Color set 1, with shades A to F
Color set 4, with shades A to F
Color set 4, with shades A to F
Color set 7, with shades A to F
Color set 7, with shades A to F
Color set 10, with shades A to F
Color set 10, with shades A to F
Color set 2, with shades A to F
Color set 2, with shades A to F
Color set 5, with shades A to F
Color set 5, with shades A to F
Color set 8, with shades A to F
Color set 8, with shades A to F
Color set 3, with shades A to F
Color set 3, with shades A to F
Color set 6, with shades A to F
Color set 6, with shades A to F
Color set 9, with shades A to F
Color set 9, with shades A to F

Images

Images may be placed as background images within one block. The predefined paddings do not apply to blocks with images; images fill out the entire block.
If needed, the title control may be placed on top of the images.

Responsiveness

The block layout offers responsive behavior. There are three breakpoints, which results in four supported sizes: XL, L, M, and S. As with the responsive grid (another generic layout control), these breakpoints apply both to the page and block layout. However, the page layout’s breakpoints react to screen width, whereas the breakpoints of the block layout react to the width of the control itself.

Ratios of areas in different contexts

Blocks per section XL, L M S
1

(Block 1)

 100%  100% 100%
2

(Blocks 2-3)

 75% and 25%
or
25% and 75%		 75% and 25%
or
25% and 75%		 100% each*
100% each*
2

(Blocks 4-5)

 50% and 50%  50% and 50% 100% each*
3

(Blocks 6-8)

 3 × 33%  3 × 33% 100% each*
3

(Blocks 9-11)

 2 × 25% and 1 × 50%
or
1 × 50% and 2 × 25%
or
1 × 25%, 1 × 50% and 1 × 25%		 2 × 50% and 1 × 100% over two rows
or
1 × 100% and 2 × 50% over two rows		 100% each*
100% each*
100% each*
4

(Blocks 12-15)

 4 × 25%  2 × 50% over two rows 100% each*

*Blocks wrap and are displayed underneath each other

Responsive behavior - Size XL
Responsive behavior - Size XL
Responsive behavior - Size M
Responsive behavior - Size M
Responsive behavior - Size S
Responsive behavior - Size S

Sections with Horizontal Scrolling

The width of the horizontal scrolling area in different device contexts:

 

Blocks per section XL, L M S
3 – 5 40% 40% 90%
6 – 10 22.5% 40% 90%
Responsive behavior of a section with horizontal scrolling - Size L
Responsive behavior of a section with horizontal scrolling - Size L
Responsive behavior of a section with horizontal scrolling - Size M
Responsive behavior of a section with horizontal scrolling - Size M
Responsive behavior of a section with horizontal scrolling - Size S
Responsive behavior of a section with horizontal scrolling - Size S

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

Form / Simple Form

Information
This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

Intro

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display- only mode
Form control in display- only mode
Form in edit mode
Form in edit mode
Developer Hint
The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

The default settings of the control are not ideal for all possible use cases. Instead, applications can use one of the various layouts for the S, M, L and XL sizes.

Column Layout

The  ColumnLayout control renders a form group in a column-based responsive way. Depending on its size, the group is divided into one or more columns.

  • XL – max. 4 columns
  • L – max. 3 columns
  • M – max. 2 columns
  • S – 1 column

To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns. The group elements are spread out into columns, depending on the number of group elements and their size.

Example:

  • 4 columns and 2 groups: each group will use 2 columns.
  • 3 columns and 2 groups: the larger one will use 2 columns, the smaller one 1 column.

The size of a group element will be determined by the number of visible elements assigned to it. If there are more groups than columns, every group uses only one column. So the last row of the form control will not be fully used. This will result in white space.

The form elements are spread out to the columns of a group arranged in a newspaper-like order. The position of the labels and fields depends on the size of the used column. If there is enough space, the labels are next to the fields, otherwise above the fields.

If you use the default form settings, each form group is displayed in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right side of the screen.

 

The examples show how forms with one and two form groups are displayed with and without layout balancing.

One form group with default arrangement
One form group with default arrangement
One form group with balanced column layout
One form group with balanced column layout
Two form groups with default arrangement
Two form groups with default arrangement
Two form groups with balanced column layout
Two form groups with balanced column layout

Responsive Grid Layout

The responsive grid layout is a form using a responsive grid. Depending on the available space, the groups are rendered in one or multiple columns, and the labels are rendered in the same row as the fields or above the fields. This behavior can be influenced by the properties of this layout control.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is the column layout, not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field ratio of 3:5:4
Form with a label-field ratio of 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form and simple form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form and simple form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms and simple forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – Size M (4:7:1)
Form in a split screen – Size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – Size M (3:5:4)
Form in full screen – Size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – Size M (4:8:0)
Form with long labels and fields – Size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – Size M (12:12:0)
Form with several form groups (two columns) – Size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – Size L (3:5:4)
Form with a single form group (one column) – Size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – Size L (12:12:0)
Form with several form groups (two columns) – Size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – Size XL (3:5:4)
Form with a single form group (one column) – Size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – Size XL (4:8:0)
Form with an empty column – Size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with single group in a column layout - Size XL - (12:12:0)
Form with single group in a column layout - Size XL - (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – Size XL (4:8:0)
Form with multiple form groups (two columns) – Size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – Size XL (12:12:0)
Form with two form groups (three columns) – Size XL (12:12:0)
Form with three form groups (three columns) – Size XL (12:12:0)
Form with three form groups (three columns) – Size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

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

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Use Column layout instead of Responsive Grid layout, if possible.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • If the form field doesn’t have a value, add an empty state indicator in the display-only mode. This is not a default property, so you will have to add it specifically.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Label Alignment

  • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
  • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
Information
The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

Unit of Measurement

You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

Unit of Measurement
Unit of Measurement

Amount Alignment

When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

Label

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

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.

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

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 Side Content

Dynamic side content is a layout control that displays additional content to help the user better understand the data that’s being displayed on the screen.  It is displayed in a way that flexibly adapts to different screen sizes.

App development teams can configure the behavior of the control on smaller screen sizes by following the relevant guidelines.

Dynamic side content layout
Dynamic side content layout

Usage

Use dynamic side content if:

  • You want to display information that:
    • Will enrich the main content and will help the user better perform his/her tasks;
    • Only makes sense when displayed next to the main container (side-by-side);
    • Influences the main content (for example, a filter for list; settings for chart, details for map).
  • Users should have access to all of the key functions and critical information in the app even if they do not see the side content. This is important because on smaller screen sizes it may be difficult to display the side content in a way that makes it easy for users to access.

Do not use dynamic side content if:

  • You want to display critical information that should be visible all the time. The dynamic side content is not meant to split the page into two equally important sections.
  • You want to display navigation or drilldown. For drilldown scenarios, use the Flexible Column Layout.
  • You want to display a list-detail scenario. Instead, use the Flexible Column Layout.
Information
Currently Dynamic Side Content is not available in Fiori Elements.

Layout

Dynamic side content is displayed to the left or right of the main content container.

The dynamic side content can be closed by a button that is displayed in its toolbar.

The dynamic side content can be opened, if it set to hidden, with an action within the container to which it is directly related, or by an action displayed in the container-related toolbar, if it is available.

When the dynamic side content is displayed side-by-side to the container, it doesn’t overlay it. The main container narrows down and makes space for the additional content to be displayed.

Responsiveness

The dynamic side content control is built for different screen sizes and layouts.

Different sizes of dynamic side content

The default screen layout features the side content on the left or right side of the screen, covering 25% of the screen width on a large desktop (over 1440 px).

Dynamic side content - Default layout
Dynamic side content - Default layout

On smaller screen sizes (under 1440 px), the side content occupies 33% of the screen width to accommodate the nested controls. If the side content width falls below 320 px, the side content automatically slides under the main content, unless the app development team specifies that it should disappear.

Dynamic side content - Smaller screen sizes
Dynamic side content - Smaller screen sizes

On screen sizes of less than or equal to 720 px, the side content automatically disappears from the screen (unless specified to stay under the content) and can be triggered from a preset trigger (specified within the app). When the side content is triggered, it replaces the main content. We recommend that you always place the trigger for the side content in the same location, such as the container toolbar.

If only the side content is shown and the user increases the screen size, the main content is automatically displayed again. If the user then decreases the screen size, the side content disappears (unless specified to stay under the content), and can be opened again by the trigger.

Equal split: A special view of the side content is the 50:50 view, which enables users to show more data, for example, for comparison purposes. The responsive behavior of the equal split is the same as in the standard view: The side content disappears on screen widths of less than 720 px and can only be viewed by triggering it.

Dynamic side content - Equal split
Dynamic side content - Equal split

The app development team may specify that the side content should slide under the main content when the screen is resized to a smaller width. Sliding the side content under the main content on smaller screens allows it to remain on the screen at all times. However, it may only become visible after scrolling.

Navigation

The side content is always related to the main content, so it must show content that can be triggered from the main content. This also means minimizing navigation, such as drill-ins within the side content, and displaying content that is triggered from the main content area. An example would be showing additional details such as contact information or conversation history. If a different type of data relates to the main content, app developers can implement a switcher in the side content. However, we recommend that you keep the side content free of additional navigation elements.

Triggering the side content

The side content can be set to hidden by default, and it automatically disappears when the screen width is less than or equal to 720 px (except when it is set to be under the main content).The app design team can define the trigger point. Our recommendation is to put a transparent text button with a meaningful label in the container toolbar, or an action inside the container the dynamic side content is related to. Ensure that the user can understand how to trigger the side content. Please, avoid using icons, because they can confuse the user.

Hiding the side content

The side content should be hidden from the header (top) section of the side content. The side content container itself has no header. We therefore strongly recommend that you use a toolbar control with a title, a transparent button labeled Close, and a spacer between them.

Hiding side content – From the header section
Hiding side content – From the header section

Guidelines

Dynamic Side Content in Object Page

Dynamic side content can be used within the object page. Use dynamic side content within a section if you want to give the user additional data related to this section. If you want to display additional information about the object such as a timeline, include this information as a new section.

Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page
Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page

Do not separate the screen into two panels. Do not use it for navigation, for drilldown, or for displaying information related to the entire object.

Dynamic Side Content in List Report

Do not separate the page into two panels when you are using it inside the list report. The dynamic side content should be placed directly next to the table or the chart container.

Do
Correct usage of dynamic side content in list report
Correct usage of dynamic side content in list report
Don't
Wrong usage of dynamic side content in list report
Wrong usage of dynamic side content in list report

Dynamic Side Content in Dynamic Page

Do not separate the page into two panels if you use dynamic side content within the dynamic page layout. Place the dynamic side content directly next to the page container and under the header container. The header snaps manually and both sections have their own scrollbars.

Do
Correct usage of dynamic side content in dynamic page
Correct usage of dynamic side content in dynamic page
Don't
Wrong usage of the dynamic side content in dynamic page
Wrong usage of the dynamic side content in dynamic page

Examples

Dynamic side content in object page, used with map
Dynamic side content in object page, used with map
Dynamic side content in list report, used with planning calendar
Dynamic side content in list report, used with planning calendar
Dynamic side content with table
Dynamic side content with table

Use of Controls in the Dynamic Side Content

You can use most of the main controls in the dynamic side content, such as text, simple form, chart, list, panel, tree, timeline, or feed and notes. However, you must make sure that the control doesn’t result in the appearance of a horizontal scrollbar.

Do not use complex controls, such as tables.

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

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show multiple facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • You plan to use only one single tab.

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Responsiveness – Text tabs
Responsiveness – Text tabs
Responsiveness – Icon tabs
Responsiveness – Icon tabs

In addition to the responsive overflow behavior, the icon tab bar can be forced into compact mode or even react dynamically to the application’s global density setting. See the Tab Density section for details.

When the screen space does not allow to show all tabs on the main tab bar, an overflow appears on the far right, containing all remaining tabs that do not fit on the screen.

Responsiveness – Overflow
Responsiveness – Overflow

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters next to the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels do not become too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure that the UpperCase property is disabled and that you enter the labels in title case (for example: Approval Flow).

Types – Text-only without counters
Types – Text-only without counters
Types – Text-only with inline counters
Types – Text-only with inline counters

Counters and Text Tabs

If counters are used, set the property HeaderMode to “Inline” so the counters appear in brackets after the labels.

Do not use the old layout that shows the counters on top of the labels (Headermode = “Standard”).

Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Types – Icons with counters
Types – Icons with counters

Please note that starting with SAPUI5 version 1.40, you should only use the horizontal type of label (icon and label side by side).

If your labels get truncated, consider using shorter labels or text tabs (without icons), since text tabs cannot get truncated.

Types – Icons with counters and labels
Types – Icons with counters and labels
Types – Icon-only
Types – Icon-only

Tabs as Filters

If you build the tab bar as a filter, it can comprise two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 189 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Types – Filter
Types – Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Types – Process
Types – Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Warning
The overflow behavior changed in SAPUI5 version 1.80. Tabs from the overflow are shown on the main tab bar as long as they are selected. This may disrupt the order of your process and give the impression of a false step order. We are working on a fix for this issue.

Hierarchies

The tab bar supports hierarchies, allowing multiple tabs underneath one main tab. This way, you can group several tabs together, with the main tab acting as a headline.

Subtabs

The example on the right shows the main tab Notes with two subtabs, Internal and External, with no specific hierarchy except for their order.

Types – Subtabs
Types – Subtabs

Nested Tabs

Nesting allows deeper hierarchies with indentations to indicate the level of each tab.

By default, the property maxNestingLevel is “0” (zero). To enable nesting, adjust this value to the highest level of nesting that your app allows.

Types – Nested tabs
Types – Nested tabs

Behavior and Interaction

Clicking a Tab

To navigate through the views, the user clicks the tabs.

Optional behavior: If the user clicks a tab that is already open, the container collapses. It opens again when the user clicks any tab.

Use the expandable property to specify whether users can collapse the tab container (default = “true”):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the expandable property to “false”.

The expandable property controls the initial state of the container. Do not change the default state (“true”).

Changing the Order of Tabs

You can allow users to rearrange the tab order in a desktop environment (property: enableTabReordering). If this feature is enabled, users can drag and drop tabs to reorder them, either directly on the tab bar or inside the overflow menu.

It is also possible to drag and drop tabs from the tab bar to the overflow menu and vice versa.

If nesting is enabled (property maxNestingLevel > 0), users can choose the level at which they want to drop a tab.

Dragging a tab activates a visual indicator for positioning the tab. For example, dragging tab 8 on top of tab 5 makes tab 8 the child of the now highlighted tab 5 (see image 1).

If the user drags a tab between two other tabs, the indicator shows the level at which level the tab will be nested (see image 2).

Interaction - Tab nesting using drag and drop (1 of 2)
Interaction - Tab nesting using drag and drop (1 of 2)
Interaction - Tab nesting using drag and drop (2 of 2)
Interaction - Tab nesting using drag and drop (2 of 2)
Information
Do not use this feature for tabs as process steps to ensure that consecutive steps do not get mixed up.

Styles

Tab Density

The default responsive design of the icon tab bar applies to both compact and cozy modes. However, in addition to this responsive behavior, the control can be forced into a compact mode, or even react dynamically to the application’s global density setting. This feature can be used to:

  • Save vertical space on the page (applies to both text and icon tabs)
  • Save horizontal space (icon tabs only; this is especially helpful when there are many tabs)
  • Generally use less space on mobile devices
  • Reduce noise when there are already more important visual elements on the screen (primarily icon tabs)

The property for the override is called tabDensityMode, which can be set to “Cozy”, “Compact”, or “Inherit”. “Cozy” is the default setting that renders the control in its regular dimensions. “Compact” reduces the control’s height and icon sizes (if applicable), even if there would be enough space for the cozy design. “Inherit” instructs the control to follow the global density mode defined for the application. For backward compatibility, the default setting is “Cozy”.

The following image shows some types of tabs with their default style (cozy, left) and the reduced density mode (compact, right).

Style – Tab density
Style – Tab density

Colors

The two different styles (round tabs and text only) are discussed in the Types section. In both cases, you can use semantic colors to give users additional orientation.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors. For more information, see How to Use Semantic Colors.

Developer Hint
To apply semantic colors to the icons and the text-only tabs, you can use the property sap.ui.core.IconColor.

Example

In the example below, one step in the process is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles – Colors
Styles – Colors

Guidelines

Apply the styles as follows:

  • Icons only: Use this option if you have only 4-5 tabs that can be very clearly identified by their icon. If a short description is needed, use icons and labels.
  • Text only: Use this option if you have more than 4-5 tabs, or if there are no clear icons to represent the content. The text-only style also allows for longer labels. Set the property HeaderMode to “Inline”.
Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B. This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Panel

The panel is a container for grouping and displaying information. It can be collapsed to save space on the screen.

Usage

Use the panel if:

  • You need to group or display information.
  • You want to give users the option of hiding this information.
  • You want to show additional information on demand (for example, a panel could show optional input fields for an advanced search).

Do not use the panel if:

  • You are designing an object page. Never use panels in the object page content area.

Responsiveness

If the width of the panel is set to 100% (default), the panel and its children are resized responsively, depending on its parent container.

Layout

  • The panel control is a container for controls.
  • The panel can have a solid or semi-transparent background.
  • The panel always includes a header.
  • An infobar can be added to the panel to show extra information.

Examples

Panel with a header text
Panel with a header text
Panel with a header toolbar and a infobar
Panel with a header toolbar and a infobar

Types

There are two types of panels: fixed and expandable.

Fixed Panel

Fixed panels are useful for grouping custom content. They include headers and infobars.

Fixed panel with a picture
Fixed panel with a picture

Expandable Panel

Expandable panels are much like fixed panels, except their content can be expanded and collapsed by clicking on the title bar.

Expandable panel – Collapsed
Expandable panel – Collapsed
Expandable panel – Expanded
Expandable panel – Expanded

Components

A panel consists of a title bar with a header text or header toolbar, an infobar (optional), and a content area.

The title inside the title bar can be added by using the “headerText” property. If you use the “headerToolbar” aggregation, the “headerText” property is ignored. With the “headerToolbar” aggregation, you can add a toolbar with any toolbar content inside the title bar. For example, if you need a title text on the left and some action buttons on the right, add a title to the toolbar’s content aggregation, toolbar spacer, and then your buttons.

Header toolbar of a panel
Header toolbar of a panel

Behavior and Interaction

Expand/Collapse

  • When the panel is expandable, an arrow icon (pointing to the right) appears in front of the header.
  • Click anywhere on the title bar to expand and collapse the content area.
  • When the animation is activated, expand/collapse uses a smooth animation to open or close the content area.
  • When the panel expands, the arrow icon rotates 90 degrees clockwise.
  • When the panel collapses, the arrow icon rotates 90 degrees counterclockwise.
  • The buttons in the header can be clicked separately.

Example

Overflow Scrolling (Content Area)

  • By setting the height to use the default property “auto”, the height of the content area will automatically be adjusted to match the height of its content.
  • When the height of the panel is set to a fixed size, the content area can be scrolled through.

Panel With Scrolling

Panel with a fixed height (scrolling activated)
Panel with a fixed height (scrolling activated)

Panel Without Scrolling

Panel with auto height (no scrolling)
Panel with auto height (no scrolling)

Guidelines

  • Nesting two or more panels is not recommended.
  • Do not stack too many panels on one page.

Exceptions

If you add a header toolbar (sap.m.Toolbar) via aggregations, it will overwrite the “headerText” property.

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

  • Panel (SAPUI5 samples)
  • Panel (SAPUI5 API reference)

Flexible Grid

The flexible grid control allows you to divide a layout into multiple columns and rows in which you can place UI elements. You can also customize the grid by aligning and arranging your elements to suit your content.

Since the flexible grid behaves responsively, it is suitable for both desktop and mobile devices. Depending on the available screen width, an optimized layout is loaded to ensure the best possible user experience on each device.

Example of a flexible grid layout
Example of a flexible grid layout
Information

Flexible grid uses the properties of the CSS grid. For more information,
see the CSS Grid Layout on the Mozilla Developer Network.

The grid is not fully supported by all browser platforms. It doesn’t work with Internet Explorer 11.

When to Use

The flexible grid can be used as an underlying layer for different types of page layouts, much like a template. You place elements such as cards or other SAP Fiori UI elements in the grid. This layout approach helps maintain one coherent experience within a page or across several pages.

Keep in mind that the elements placed in your grid are empty containers. Therefore, your grid layout is invisible until there is content in them to display.

Flexible grid with examples of cell areas
Flexible grid with examples of cell areas
Flexible grid with examples of Fiori UI elements placed in cell areas
Flexible grid with examples of Fiori UI elements placed in cell areas

The flexible grid can be used within different types of pages, such as the home page or other pages of an application. For an overview of the application page types, see the Explore page.

You can determine how you want to use the available space in your grid and how the content flows by adding breakpoints.

Some features and behaviors are configurable to enable the flexible grid for a variety of use cases. 

Flexible grid with example of space and content flow
Flexible grid with example of space and content flow
Flexible grid with example of space and content flow
Flexible grid with example of space and content flow

Use the flexible grid if:

  • You want to display your content in columns and rows so that it adapts flexibly to changes in the screen size.
  • You want to display your content in full-page layouts so that your content flows but stays aligned and spaced out evenly.
  • The focus of your layout is on flexibility and responsiveness, not on constraining the content to grid cells.
  • You want to include explicit or nested grid elements to have your elements or content adapt to any row or column size and to any breakpoints.
  • You want to have only one implementation for all devices.
  • You want to embed elements from another page into one of the columns.

Do not use the flexible grid if:

  • Your content is not appropriate for a card-like format, or for simple forms. For example, do not use the flexible grid for displaying a list or table that a user can edit or that needs to show a large number of items. Use a grid table instead.
  • You want to manage complex content, such as datasets that need to be extensively sorted, grouped, filtered, or edited. In this case, use a grid table instead.
  • You want to display a set of items on a grid. Consider using the grid list instead.
  • Your layout needs to be defined only by columns or only by rows, not both. Use a flex box instead.

Components

A  Column Elements can be placed in columns so they align horizontally in the layout.
B  Row Elements can be placed in rows so they align vertically in the layout.
C  Gutter – Column The gutters define the spacing between cells (space between columns).
D  Gutter – row The gutters define the spacing between cells (space between rows).
E  Margin – left The margins define the outer spacing of the grid layout (left, right, top, bottom).
F  Margin – bottom
G  Margin – right
H  Margin – top
I  Cell The cell is the smallest feature of the flexible grid. It is conceptually much like a table cell, and elements can be placed in a cell (or combination of cells) and aligned in columns and rows. The size of a cell depends on the width of a column and the height of a row. The width may differ from the height.
J  Cell area In this example, the elements are placed or mapped to 2 cells (aligned horizontally) and 2 cells (aligned vertically).

Flexible Grid Elements

You can place elements (SAP Fiori controls) in the flexible grid and then define the size of the elements by how they are laid out in the grid.

The order in which you add the elements determines how they appear in the layout.

Flexible grid elements with 9 columns and 5 rows
Flexible grid elements with 9 columns and 5 rows
Flexible grid elements with 9 columns and 5 rows
Flexible grid elements with 9 columns and 5 rows

Placement and Nesting

The grid layout can be used as a standalone, or inside other layout containers such as another page, a header, or a dialog.

The grid layout supports nesting, which allows you to place a flexible grid layout inside a grid element.

Flexible grid with a nested grid
Flexible grid with a nested grid
Flexible grid with a nested grid
Flexible grid with a nested grid

Behavior and Interaction

Layout Flexibility

You can use the flexible grid to define a layout for more than one page. This means you don’t need to define a template for each page.

Size of Elements in a Flexible Grid

Depending on the use case, you can assign specific sizes to a grid element to ensure that the content in the grid layout is displayed correctly.

Minimum and maximum size

If necessary, you can apply a minimum and/or maximum size to a grid element. For example, if the minimum width for a grid element is three columns, the space used by the element will never be less than three columns, even when the layout is resized.

Grid elements can also have a combination of specified minimum and maximum sizes (such as a range of sizes). However, you can only use whole (not half) columns or rows when referencing a size unit (for example, 2×3, 4×4).

Note: Keep in mind that the number of columns for a grid element should never be less than the minimum number of columns of the flexible grid layout in its smallest form factor.

Full-width elements

Grid elements can be defined to span the full width of the grid (using all the columns) for one or several rows in the grid layout.

Flexible grid and example of column widths
Flexible grid and example of column widths
Flexible grid and example of column widths
Flexible grid and example of column widths

Defining How the Content Fills the Space

You can define how the content fills the space of grid elements by adjusting the content to the height of the row. This can affect visual balance and consistency in the overall flexible grid layout. You can also choose to constrain content to the height of the elements (with a card control, for example).

Conversely, if the content doesn’t fill up all the space of the layout elements, you can include areas of white space (or empty space) to have “breathing” room in your layout.

Defining columns

Always use the full width of the layout elements, so that the content spans across the full width of the page or the width of the column.

Defining rows

When placing grid elements in rows, we recommend adding some white space (breathing space) between rows, especially if the content displayed in the elements is dense.

Note: You can choose whether to use the full height of the layout elements or only the desired space.

Flexible grid with example of how content adapts to the space in the layout
Flexible grid with example of how content adapts to the space in the layout
Flexible grid with example of how content adapts to the space in the layout
Flexible grid with example of how content adapts to the space in the layout

Responsiveness

You can enable your flexible grid to adapt to the size of the screen on a device (desktop, tablet, or phone), as well as to the display orientation or the available space on the screen.

Responsiveness is fully configurable by the developer. It is possible to create an adjustable layout with the flexible grid so that the content “breathes” (includes empty space). In this case, the columns adjust the content in the layout depending on the width of the overall grid.

You can define a new flexible grid at any breakpoint. With the flexible grid properties it is possible to define:

  • Columns, rows, and their sizes in the grid
  • Vertical and horizontal gaps, space between the grid elements
  • The flow algorithm when new elements are added to the grid.

The size of grid elements (or controls) is overridden when you specify how much space is used in the grid, or how many columns and rows the grid contains overall. If you specify the row or column from which an element starts, this overrides the automatically calculated position.

Flexible grid with responsiveness and element positioning
Flexible grid with responsiveness and element positioning
Flexible grid with responsiveness and shifted positioning
Flexible grid with responsiveness and shifted positioning

Row Height

There are only as many rows as needed by the grid elements. When resized, the grid adjusts the number of rows as content is added based on your predefined settings, such as the maximum number of rows and the minimum/maximum width of the grid.

Number of Columns

There are three options for defining the number of available columns in your flexible grid:

  • Predefined number of columns using breakpoints
    You can apply a predefined number of columns by using breakpoints based on the width of the screen. The width of the screen depends on the size of the device (S, M, L, and XL). When resizing the screen, the columns can “breathe” and every column width can be adjusted until a breakpoint is reached.
  • Flexible number of columns
    The number of columns is calculated based on the available width of the screen. When you resize the screen, the columns adjust in width to allow the content to adapt to the space on the page when new columns are added or removed.
  • Fixed number of columns and column width
    In this case, the number and size of columns is predefined. Therefore, depending on the width of the flexible grid, it might be necessary to show horizontal scroll bars. This approach is not responsive and should be avoided in layouts used on different form factors.

Columns and Breakpoints

Note: For reference only. For more information, see Responsive Spacing System.

 Screen  Breakpoints
S (phone) ≤ 599 px
M (Tablet) 600 – 1023 px
L (Desktop)  1024 – 1439 px
XL (Desktop) 1440 – 1919 px

Arranging Grid Elements

We recommend arranging flexible grid elements in a sequence so that the elements have a specific position in the layout.

Whether you add, remove, or rearrange elements, elements already in the grid will shift to the next or previous column (or row), depending on where they were initially positioned.

Content Flow

You can arrange layout elements so that the content displays or flows both horizontally and vertically in the flexible grid. If a column is set to auto-width and other columns have a fixed size, the auto-width column expands to the maximum width available, as defined by the overall grid width.

Flexible grid with auto-width column
Flexible grid with auto-width column

Here are two flow designs for the flexible grid:

Z-Flow (default)

Grid items are displayed in a sequence row-by-row (or Z shape-pattern), top-to-bottom. The reading order is left-to-right (when RTL is enabled, it is right-to-left).

ᴎ-Flow

Grid items are displayed in a column-by-column, top-to-bottom sequence (or N-shape pattern). The reading order is left-to-right (when RTL is enabled, it is right-to-left).

Resizing the Screen

When resizing the screen, the grid layout adapts to the available space, and the grid elements are automatically rearranged based on their position in the sequence. This allows you to apply the flexible grid to a variety of devices and use cases.

Developer Hint
The flexible grid is fully configurable by the developer. It is possible to let columns “breathe”, which means that the column widths grow/shrink depending on the grid size.
Example of responsiveness and size of columns
Example of responsiveness and size of columns
Example of responsiveness and resizing of columns
Example of responsiveness and resizing of columns

Implicit and Explicit Grid

The grid creates (implicit) rows and columns on its own when needed. For example, if a grid element is positioned in a row or column that is not explicitly sized, implicit rows or columns are created to hold it.

Developer Hint
Explicit grids are rows and columns defined with gridTemplateColumns and gridTemplateRows. Implicit rows or columns are defined with gridAutoColumns and gridAutoRows.
Flexible grid with explicit and implicit grids
Flexible grid with explicit and implicit grids

Top Tips

Include UI elements and controls that make sense in a flexible grid layout. Their content should adapt appropriately when the grid is resized, or the elements rearranged.

Include UI elements for which you might want to customize both the vertical and horizontal alignment.

If you want to include nested grids, consider the UX investment you’ll need to make to achieve the desired visual and structural result with your grid layout.

We don’t recommend using several nested grids, as it might result in an over-complicated UI layout. Also, the UI elements in your grid might not align at all with other UI elements of the grid as intended.

Properties

sap.ui.layout.cssgrid.CSSGrid

The following additional properties are available for the flexible grid:

  • The property width sets the width of the flexible grid.
  • The property gridTemplateColumns defines the number of columns in the flexible grid.
  • The property gridTemplateRows defines the number of rows in the flexible grid.
  • The property gridColumnGap sets the width of the gap (gutter) between columns.
  • The property gridRowGap sets the width of the gap (gutter) between rows.

Related Topics

Elements and Controls

Implementation

Form / Simple Form

Information
This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

Intro

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display only
Form control in display only
Mixed form with editable and non-editable fields
Mixed form with editable and non-editable fields
Developer Hint
The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms and simple forms. These should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field ratio 3:5:4
Form with a label-field ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form and simple form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form and simple form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size L and XL
Form in size L and XL
Developer Hint
For forms and simple forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – size M (3:5:4)
Form in full screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Column Layout

If you use the default form settings, each form group displays in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right of the screen.

To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns (layout: ColumnLayout).

You can use this option to distribute the content for up to two form groups. As soon as there are more than two form groups, the display reverts to the default layout (one column per form group).

The examples below show how forms with one and two form groups display with and without layout balancing.

One form group with default arrangement
One form group with default arrangement
One form group with balanced column layout
One form group with balanced column layout
Two form groups with default arrangement
Two form groups with default arrangement
Two form groups with balanced column layout
Two form groups with balanced column layout

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

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

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Label Alignment

  • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
  • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
Information
The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

Unit of Measurement

You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

Unit of Measurement
Unit of Measurement

Amount Alignment

When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

Label

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

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.

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

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

Block Layout

Information

This layout has been designed specifically for the tool landscape for the SAP Cloud Platform. It is not intended for use in regular SAP Fiori applications. 

Intro

The block layout is used to display content in a section-based manner. It features horizontal and vertical subdivisions and full-width banners seen frequently in contemporary web design. Background colors are attached directly to these areas within the layout. Also, special full-width sections of the block layout enable horizontal scrolling through a set of areas.

General page structure of a tool using the block layout
General page structure of a tool using the block layout

Usage

Use the block layout if:

  • You want to display section-based content. Place elements next to each other to indicate a content relationship.

Do not use the block layout if:

  • You want to display properties or features of one content item. Use the object page floorplan instead.
  • You want to display KPIs in the dashboard-variant. Use the overview page or a layout using cards instead.

Block layout case examples include landing pages and catalog-like pages.

In landing pages, the block layout may serve as a banner-like presentation of illustrative icons with associated text. By placing pictorial and textual elements side by side in different areas, a content relationship is established. In catalog-like layouts, the block layout serves as a flexible container for diverging content, such as headings, explanatory texts, code snippets, remarks, and examples.

It is also possible to have clickable blocks with their own hover and pressed states.

Layout

The block layout is divided into horizontal sections, which take on the full width of the available screen real estate. Their screen height is determined by their inner content, which prevents vertical scrolling.

If needed, the width of sections can also be set to the following predefined ratios (for the sizes XL, L and M):

  • 1 block: 100%
  • 2 blocks:
    • 50% and 50% or
    • 75% and 25% or
    • 25% and 75%
  • 3 blocks:
    • 3 × 33% or
    • 2 × 25% and 50% or
    • 50% and 2 × 25% or
    • 25% and 50% and 25%
  • 4 blocks: 4 × 25%

Block layouts can also contain sections that allow horizontal scrolling. These sections always have a width of 100%.

Schematic block layout
Schematic block layout
Schematic block layout with a section scrolling horizontally
Schematic block layout with a section scrolling horizontally

Components

Block layout components
Block layout components

1 – Section

1a – Section Title

2 – Block

2a – Block Title – can be text or a link.

2b – Block Body – can contain text or other controls.

Guidelines

  • Links within a block must lead to areas outside of the block. In addition, controls must update only their own containers.
  • Usage of disabled, emphasized or subtle links as block titles is not recommended. Dark background designs, for example when using the Accent variant, are not fully supported with regards to accessibility when used with links as titles.

Types

There are four types of block layouts:

  1. Default: This layout does not use any background colors.
  2. Dashboard: This layout type uses white blocks with spacing around them, making each block look like a card.
  3. Light: Areas use predefined colors found in the SAP Fiori 3 Quartz Light theme. These colors follow a specific order that is defined in the control. If there are more than six areas, the background colors start over beginning with the initial color.
  4. Accent: Each row contains a range of colors derived from one accent color, and these colors are used alternately. If required by the control, you can display multiple gray blocks: the different shades of gray will then be displayed alternately, beginning with the initial color.

Light Color Set

For the Light variant, use colors as follows:

  • block color A for the section title block.
  • block colors B, C, D, E, F and G for the blocks, one after another.
  • block color H for the footer.
Color set for the
Color set for the "Light" block layout type

Accent Color Sets

Row (Section) Color Sets

For the Accent variant of the block layout, you can use a different color set for each row (sap.ui.layout.BlockLayoutRow, property:rowColorSet). This enables different starting colors for the row coloring, and prevents color coalescence in the responsive behavior of the block layout.

Cell (Block) Colors

There are 10 predefined color sets that you can use as accent variants, each with 6 different shades.

To change the background of a particular block, set the desired color set (sap.ui.layout.BlockLayoutCell, property: backgroundColorSet) and color shade (sap.ui.layout.BlockLayoutCell, property: backgroundColorShade) accordingly.

Color set 1, with shades A to F
Color set 1, with shades A to F
Color set 4, with shades A to F
Color set 4, with shades A to F
Color set 7, with shades A to F
Color set 7, with shades A to F
Color set 10, with shades A to F
Color set 10, with shades A to F
Color set 2, with shades A to F
Color set 2, with shades A to F
Color set 5, with shades A to F
Color set 5, with shades A to F
Color set 8, with shades A to F
Color set 8, with shades A to F
Color set 3, with shades A to F
Color set 3, with shades A to F
Color set 6, with shades A to F
Color set 6, with shades A to F
Color set 9, with shades A to F
Color set 9, with shades A to F

Images

Images may be placed as background images within one block. The predefined paddings do not apply to blocks with images; images fill out the entire block.
If needed, the title control may be placed on top of the images.

Responsiveness

The block layout offers responsive behavior. There are three breakpoints, which results in four supported sizes: XL, L, M, and S. As with the responsive grid (another generic layout control), these breakpoints apply both to the page and block layout. However, the page layout’s breakpoints react to screen width, whereas the breakpoints of the block layout react to the width of the control itself.

Ratios of areas in different contexts

Blocks per section XL, L M S
1

(Block 1)

 100%  100% 100%
2

(Blocks 2-3)

 75% and 25%
or
25% and 75%		 75% and 25%
or
25% and 75%		 100% each*
100% each*
2

(Blocks 4-5)

 50% and 50%  50% and 50% 100% each*
3

(Blocks 6-8)

 3 × 33%  3 × 33% 100% each*
3

(Blocks 9-11)

 2 × 25% and 1 × 50%
or
1 × 50% and 2 × 25%
or
1 × 25%, 1 × 50% and 1 × 25%		 2 × 50% and 1 × 100% over two rows
or
1 × 100% and 2 × 50% over two rows		 100% each*
100% each*
100% each*
4

(Blocks 12-15)

 4 × 25%  2 × 50% over two rows 100% each*

*Blocks wrap and are displayed underneath each other

Responsive behavior - Size XL
Responsive behavior - Size XL
Responsive behavior - Size M
Responsive behavior - Size M
Responsive behavior - Size S
Responsive behavior - Size S

Sections with Horizontal Scrolling

The width of the horizontal scrolling area in different device contexts:

 

Blocks per section XL, L M S
3 – 5 40% 40% 90%
6 – 10 22.5% 40% 90%
Responsive behavior of a section with horizontal scrolling - Size L
Responsive behavior of a section with horizontal scrolling - Size L
Responsive behavior of a section with horizontal scrolling - Size M
Responsive behavior of a section with horizontal scrolling - Size M
Responsive behavior of a section with horizontal scrolling - Size S
Responsive behavior of a section with horizontal scrolling - Size S

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

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show multiple facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • You plan to use only one single tab.

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Responsiveness – Text tabs
Responsiveness – Text tabs
Responsiveness – Icon tabs
Responsiveness – Icon tabs

In addition to the responsive overflow behavior, the icon tab bar can be forced into compact mode or even react dynamically to the application’s global density setting. See the Tab Density section for details.

When the screen space does not allow to show all tabs on the main tab bar, an overflow appears on the far right, containing all remaining tabs that do not fit on the screen.

Responsiveness – Overflow
Responsiveness – Overflow

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters next to the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels do not become too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure that the UpperCase property is disabled and that you enter the labels in title case (for example: Approval Flow).

Types – Text-only without counters
Types – Text-only without counters
Types – Text-only with inline counters
Types – Text-only with inline counters

Counters and Text Tabs

If counters are used, set the property HeaderMode to “Inline” so the counters appear in brackets after the labels.

Do not use the old layout that shows the counters on top of the labels (Headermode = “Standard”).

Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Types – Icons with counters
Types – Icons with counters

Please note that starting with SAPUI5 version 1.40, you should only use the horizontal type of label (icon and label side by side).

If your labels get truncated, consider using shorter labels or text tabs (without icons), since text tabs cannot get truncated.

Types – Icons with counters and labels
Types – Icons with counters and labels
Types – Icon-only
Types – Icon-only

Tabs as Filters

If you build the tab bar as a filter, it can comprise two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 189 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Types – Filter
Types – Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Types – Process
Types – Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Hierarchies

The tab bar supports hierarchies, allowing multiple tabs underneath one main tab. This way, you can group several tabs together, with the main tab acting as a headline.

Subtabs

The example on the right shows the main tab Notes with two subtabs, Internal and External, with no specific hierarchy except for their order.

Types – Subtabs
Types – Subtabs

Nested Tabs

Nesting allows deeper hierarchies with indentations to indicate the level of each tab.

Types – Nested Tabs
Types – Nested Tabs

Behavior and Interaction

Clicking a Tab

To navigate through the views, the user clicks the tabs.

Optional behavior: If the user clicks a tab that is already open, the container collapses. It opens again when the user clicks any tab.

Use the expandable property to specify whether users can collapse the tab container (default = “true”):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the expandable property to “false”.

The expandable property controls the initial state of the container. Do not change the default state (“true”).

Changing the Order of Tabs

Applications can allow users to rearrange the tab order when working in a desktop environment (property: enableTabReordering). If this feature is enabled, users can use drag and drop to reorder tabs, either directly on the tab bar or inside the overflow menu. It is also possible to drag and drop tabs from the tab bar to the overflow menu and vice versa.

Please note that this feature is not available for tabs as process steps to ensure that consecutive steps do not get mixed up.

Styles

Tab Density

The default responsive design of the icon tab bar applies to both compact and cozy modes. However, in addition to this responsive behavior, the control can be forced into a compact mode, or even react dynamically to the application’s global density setting. This feature can be used to:

  • Save vertical space on the page (applies to both text and icon tabs)
  • Save horizontal space (icon tabs only; this is especially helpful when there are many tabs)
  • Generally use less space on mobile devices
  • Reduce noise when there are already more important visual elements on the screen (primarily icon tabs)

The property for the override is called tabDensityMode, which can be set to “Cozy”, “Compact”, or “Inherit”. “Cozy” is the default setting that renders the control in its regular dimensions. “Compact” reduces the control’s height and icon sizes (if applicable), even if there would be enough space for the cozy design. “Inherit” instructs the control to follow the global density mode defined for the application. For backward compatibility, the default setting is “Cozy”.

The following image shows some types of tabs with their default style (cozy, left) and the reduced density mode (compact, right).

Style – Tab density
Style – Tab density

Colors

The two different styles (round tabs and text only) are discussed in the Types section. In both cases, you can use semantic colors to give users additional orientation.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors. For more information, see How to Use Semantic Colors.

Developer Hint
To apply semantic colors to the icons and the text-only tabs, you can use the property for sap.ui.core.IconColor.

Example

In the example below, one step in the process is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles – Colors
Styles – Colors

Guidelines

Apply the styles as follows:

  • If you have only a few tabs that can easily be visualized with icons, use the icon-only tabs. If a short description is needed, use icons and labels.
  • If the content cannot easily be identified by an icon, use the text-only tabs. They also allow for longer labels.
  • If you are using the icon tab bar in the object view floorplan, use either icon-only or text-only tabs.
    Icons only:
    Use this option if you have only 4-5 tabs that can be very clearly identified by their icon.
    Text only:
    Use this option if you have more than 4-5 tabs, or if there are no clear icons to represent the content. Set the property HeaderMode to “Inline”.
Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B. This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Form / Simple Form

Information
This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

Intro

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display only
Form control in display only
Mixed form with editable and non-editable fields
Mixed form with editable and non-editable fields
Developer Hint
The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms and simple forms. These should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field ratio 3:5:4
Form with a label-field ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form and simple form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form and simple form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms and simple forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – size M (3:5:4)
Form in full screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Column Layout

If you use the default form settings, each form group displays in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right of the screen.

To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns (layout: ColumnLayout).

You can use this option to distribute the content for up to two form groups. As soon as there are more than two form groups, the display reverts to the default layout (one column per form group).

The examples below show how forms with one and two form groups display with and without layout balancing.

One form group with default arrangement
One form group with default arrangement
One form group with balanced column layout
One form group with balanced column layout
Two form groups with default arrangement
Two form groups with default arrangement
Two form groups with balanced column layout
Two form groups with balanced column layout

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

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

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Label Alignment

  • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
  • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
Information
The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

Unit of Measurement

You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

Unit of Measurement
Unit of Measurement

Amount Alignment

When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

Label

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

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.

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

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

Carousel

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

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

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

Usage

Use the carousel if:

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

Do not use the carousel if:

  • The items you want to display are uniform.

Responsiveness

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

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

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

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

Carousel - Size S
Carousel - Size S

Carousel - Size M
Carousel - Size M

Carousel - Size L
Carousel - Size L

Layout

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

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

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

Displaying multiple items

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

Schematic layout of the carousel
Schematic layout of the carousel

Behavior and Interaction

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

Navigation for Single Items

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

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

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

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

Paging button – Previous Page
Paging button – Previous Page
Paging button – Next Page (hover)
Paging button – Next Page (hover)

Navigation for Multiple Items

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

Carousel with multiple items
Carousel with multiple items

Looping

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

Paging

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

Paging indicator
Paging indicator

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

Paging indicator
Paging indicator

Resources

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

Elements and Controls

Image (guidelines)

Implementation

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking or tapping the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show multiple facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • You plan to use only one single tab.

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Responsiveness – Text tabs
Responsiveness – Text tabs
Responsiveness – Icon tabs
Responsiveness – Icon tabs

In addition to the responsive overflow behavior, the icon tab bar can be forced into compact mode or even react dynamically to the application’s global density setting. See the Tab Density section for details.

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters next to the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels do not become too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure that the UpperCase property is disabled and that you enter the labels in title case (for example: Approval Flow).

Types – Text-only without counters
Types – Text-only without counters
Types – Text-only with inline counters
Types – Text-only with inline counters

Counters and Text Tabs

If counters are used, set the property HeaderMode to “Inline” so the counters appear in brackets after the labels.

Do not use the old layout that shows the counters on top of the labels (Headermode = “Standard”).

Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Types – Icons with counters
Types – Icons with counters

Please note that starting with SAPUI5 version 1.40, you should only use the horizontal type of label (icon and label side by side).

If your labels get truncated, consider using shorter labels or text tabs (without icons), since text tabs cannot get truncated.

Types – Icons with counters and labels
Types – Icons with counters and labels
Types – Icon-only
Types – Icon-only

Tabs as Filters

If you build the tab bar as a filter, it can comprise two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 189 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Types – Filter
Types – Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Types – Process
Types – Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Behavior and Interaction

Clicking/Tapping on a Tab

To navigate through the views, the user clicks or taps the tabs.

Optional behavior: If the user clicks or taps a tab that’s already open, the container collapses. It opens again when the user clicks any tab.

Use the expandable property to specify whether users can collapse the tab container (default = “true”):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the expandable property to “false”.

The expandable property controls the initial state of the container. Do not change the default state (“true”).

Changing the Order of Tabs

Applications can allow users to rearrange the tab order when working in a desktop environment (property: enableTabReordering). If this feature is enabled, users can use drag and drop to reorder tabs, either directly on the tab bar or inside the overflow menu. It is also possible to drag and drop tabs from the tab bar to the overflow menu and vice versa.

Please note that this feature is not available for tabs as process steps to ensure that consecutive steps do not get mixed up.

Interaction – Rearranging tabs
Interaction – Rearranging tabs
Interaction – Rearranging tabs in the overflow menu
Interaction – Rearranging tabs in the overflow menu
Interaction – Rearranging tabs between bar and overflow menu
Interaction – Rearranging tabs between bar and overflow menu

Styles

Tab Density

The default responsive design of the icon tab bar applies to both compact and cozy modes. However, in addition to this responsive behavior, the control can be forced into a compact mode, or even react dynamically to the application’s global density setting. This feature can be used to:

  • Save vertical space on the page (applies to both text and icon tabs)
  • Save horizontal space (icon tabs only; this is especially helpful when there are many tabs)
  • Generally use less space on mobile devices
  • Reduce noise when there are already more important visual elements on the screen (primarily icon tabs)

The property for the override is called tabDensityMode, which can be set to “Cozy”, “Compact”, or “Inherit”. “Cozy” is the default setting that renders the control in its regular dimensions. “Compact” reduces the control’s height and icon sizes (if applicable), even if there would be enough space for the cozy design. “Inherit” instructs the control to follow the global density mode defined for the application. For backward compatibility, the default setting is “Cozy”.

The following image shows some types of tabs with their default style (cozy, left) and the reduced density mode (compact, right).

Style – Tab density
Style – Tab density

Colors

The two different styles (round tabs and text only) are discussed in the Types section. In both cases, you can use semantic colors to give users additional orientation.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors. For more information, see How to Use Semantic Colors.

Developer Hint
To apply semantic colors to the icons and the text-only tabs, you can use the property for sap.ui.core.IconColor.

Example

In the example below, one step in the process is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles – Colors
Styles – Colors

Guidelines

Apply the styles as follows:

  • If you have only a few tabs that can easily be visualized with icons, use the icon-only tabs. If a short description is needed, use icons and labels.
  • If the content cannot easily be identified by an icon, use the text-only tabs. They also allow for longer labels.
  • If you are using the icon tab bar in the object view floorplan, use either icon-only or text-only tabs.
    Icons only:
    Use this option if you have only 4-5 tabs that can be very clearly identified by their icon.
    Text only:
    Use this option if you have more than 4-5 tabs, or if there are no clear icons to represent the content. Set the property HeaderMode to “Inline”.
Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B. This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Panel

The panel is a container for grouping and displaying information. It can be collapsed to save space on the screen.

Usage

Use the panel if:

  • You need to group or display information.
  • You want to give users the option of hiding this information.
  • You want to show additional information on demand (for example, a panel could show optional input fields for an advanced search).

Do not use the panel if:

  • You are designing an object page. Never use panels in the object page content area.

Example

  • Panel - Value Help Dialog Closed
  • Panel - Value Help Dialog Open

Responsiveness

If the width of the panel is set to 100% (default), the panel and its children are resized responsively, depending on its parent container.

Layout

  • The panel control is a container for controls.
  • The panel can have a solid or semi-transparent background.
  • The panel always includes a header.
  • An infobar can be added to the panel to show extra information.

Examples

Panel with a title toolbar
Panel with a title toolbar
Panel with a title toolbar and infobar
Panel with a title toolbar and infobar

Types

There are two types of panels: fixed and expandable.

Fixed Panel

Fixed panels are useful for grouping custom content. They include headers and info toolbars.

Fixed panel
Fixed panel

Expandable Panel

Expandable panels are much like fixed panels, except their content can be expanded and collapsed (including the info toolbar, if available).

  • Panel Expandable1
  • Panel Expandable2

Components

A panel consists of a title bar with a header text or header toolbar, an info toolbar (optional), and a content area.

The title inside the title bar can be added by using the “headerText” property. If you use the “headerToolbar” aggregation, the “headerText” property is ignored. With the “headerToolbar” aggregation, you can add a toolbar with any toolbar content inside the title bar. For example, if you need a title text on the left and some action buttons on the right, add a title to the toolbar’s content aggregation, toolbar spacer, and then your buttons.

Header toolbar of a panel
Header toolbar of a panel

Behavior and Interaction

Expand/Collapse

  • When the panel is expandable, an arrow icon (pointing to the right) appears in front of the header. Click this icon to expand the panel.
  • When the animation is activated, expand/collapse uses a smooth animation to open or close the content area.
  • When the panel expands, the arrow icon rotates 90 degrees clockwise.
  • When the panel collapses, the arrow icon rotates 90 degrees counterclockwise.
  • The buttons in the header can be clicked separately.

Example

  • Panel ExpandCollapse1
  • Panel ExpandCollapse2

Overflow Scrolling (Content Area)

  • By setting the height to use the default property “auto”, the height of the content area will automatically be adjusted to match the height of its content.
  • When the height of the panel is set to a fixed size, the content area can be scrolled through.

Panel With Scrolling

Panel with a fixed height (scrolling activated)
Panel with a fixed height (scrolling activated)

Panel Without Scrolling

Panel with auto height (no scrolling)
Panel with auto height (no scrolling)

Guidelines

  • Nesting two or more panels is not recommended.
  • Do not stack too many panels on one page.

Exceptions

If you add a header toolbar (sap.m.Toolbar) via aggregations, it will overwrite the “headerText” property.

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

  • No links

Carousel

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

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

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

Usage

Use the carousel if:

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

Do not use the carousel if:

  • The items you want to display are uniform.

Responsiveness

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

On non-touch devices, the user can navigate with Previous and Next icons displayed on the left and right of the control.

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

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

Carousel - Size S
Carousel - Size S

Carousel - Size M
Carousel - Size M

Carousel - Size L
Carousel - Size L

Layout

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

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

On non-touch devices, icons for navigating to the next or previous item either float above the left and right sides of the content area, or appear in the paging indicator area. This is controlled by the arrowsPlacement property.

Displaying multiple items

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

Schematic layout of the carousel
Schematic layout of the carousel

Behavior and Interaction

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

Navigation for Single Items

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

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

On non-touch devices, users navigate with icons.

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

Navigation – Previous
Navigation – Previous
Navigation – Next (hover)
Navigation – Next (hover)

Navigation for Multiple Items

When the user navigates left or right, the rightmost or leftmost item is moved out of the content area, and the next or previous item slides in (depending on the navigation direction).

Carousel with multiple items
Carousel with multiple items

Looping

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

Paging

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

Paging indicator
Paging indicator

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

Paging indicator
Paging indicator

Resources

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

Elements and Controls

Image (guidelines)

Implementation

Form / Simple Form

Information
This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

Intro

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display only
Form control in display only
Mixed form with editable and non-editable fields
Mixed form with editable and non-editable fields
Developer Hint
The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms and simple forms. These should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field ratio 3:5:4
Form with a label-field ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form and simple form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form and simple form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms and simple forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – size M (3:5:4)
Form in full screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Column Layout

If you use the default form settings, each form group displays in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right of the screen.

To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns (layout: ColumnLayout).

You can use this option to distribute the content for up to two form groups. As soon as there are more than two form groups, the display reverts to the default layout (one column per form group).

The examples below show how forms with one and two form groups display with and without layout balancing.

One form group with default arrangement
One form group with default arrangement
One form group with balanced column layout
One form group with balanced column layout
Two form groups with default arrangement
Two form groups with default arrangement
Two form groups with balanced column layout
Two form groups with balanced column layout

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

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

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Label Alignment

  • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
  • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
Information
The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

Unit of Measurement

You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

Unit of Measurement
Unit of Measurement

Amount Alignment

When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

Label

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

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.

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

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

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking or tapping the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show multiple facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • You plan to use only one single tab.

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Responsiveness – Icon tabs
Responsiveness – Icon tabs
Responsiveness – Text tabs
Responsiveness – Text tabs

In addition to the responsive overflow behavior, the icon tab bar can be forced into compact mode or even react dynamically to the application’s global density setting. See the Tab Density section for details.

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters next to the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels do not become too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure that the UpperCase property is disabled and that you enter the labels in title case (for example: Approval Flow).

Types – Text-only without counters
Types – Text-only without counters
Types – Text-only with inline counters
Types – Text-only with inline counters

Counters and Text Tabs

If counters are used, set the property HeaderMode to “Inline” so the counters appear in brackets after the labels.

Do not use the old layout that shows the counters on top of the labels (Headermode = “Standard”).

Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Types – Icons with counters
Types – Icons with counters

Please note that starting with SAPUI5 version 1.40, you should only use the horizontal type of label (icon and label side by side).

If your labels get truncated, consider using shorter labels or text tabs (without icons), since text tabs cannot get truncated.

Types – Icons with counters and labels
Types – Icons with counters and labels
Types – Icon-only
Types – Icon-only

Tabs as Filters

If you build the tab bar as a filter, it can comprise two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 189 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Types – Filter
Types – Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Types – Process
Types – Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Behavior and Interaction

Clicking/Tapping on a Tab

To navigate through the views, the user clicks or taps the tabs.

Optional behavior: If the user clicks or taps a tab that’s already open, the container collapses. It opens again when the user clicks any tab.

Use the expandable property to specify whether users can collapse the tab container (default = “true”):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the expandable property to “false”.

The expandable property controls the initial state of the container. Do not change the default state (“true”).

Changing the Order of Tabs

Applications can allow users to rearrange the tab order when working in a desktop environment (property: enableTabReordering). If this feature is enabled, users can use drag and drop to reorder tabs, either directly on the tab bar or inside the overflow menu. It is also possible to drag and drop tabs from the tab bar to the overflow menu and vice versa.

Please note that this feature is not available for tabs as process steps to ensure that consecutive steps do not get mixed up.

Interaction – Rearranging tabs
Interaction – Rearranging tabs
Interaction – Rearranging tabs in the overflow menu
Interaction – Rearranging tabs in the overflow menu
Interaction – Rearranging tabs between bar and overflow menu
Interaction – Rearranging tabs between bar and overflow menu

Styles

Tab Density

The default responsive design of the icon tab bar applies to both compact and cozy modes. However, in addition to this responsive behavior, the control can be forced into a compact mode, or even react dynamically to the application’s global density setting. This feature can be used to:

  • Save vertical space on the page (applies to both text and icon tabs)
  • Save horizontal space (icon tabs only; this is especially helpful when there are many tabs)
  • Generally use less space on mobile devices
  • Reduce noise when there are already more important visual elements on the screen (primarily icon tabs)

The property for the override is called tabDensityMode, which can be set to “Cozy”, “Compact”, or “Inherit”. “Cozy” is the default setting that renders the control in its regular dimensions. “Compact” reduces the control’s height and icon sizes (if applicable), even if there would be enough space for the cozy design. “Inherit” instructs the control to follow the global density mode defined for the application. For backward compatibility, the default setting is “Cozy”.

The following image shows some types of tabs with their default style (cozy, left) and the reduced density mode (compact, right).

Style – Tab density
Style – Tab density

Colors

The two different styles (round tabs and text only) are discussed in the Types section. In both cases, you can use semantic colors to give users additional orientation.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors. For more information, see How to Use Semantic Colors.

Developer Hint
To apply semantic colors to the icons and the text-only tabs, you can use the property for sap.ui.core.IconColor.

Example

In the example below, one step in the process is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles – Colors
Styles – Colors

Guidelines

Apply the styles as follows:

  • If you have only a few tabs that can easily be visualized with icons, use the icon-only tabs. If a short description is needed, use icons and labels.
  • If the content cannot easily be identified by an icon, use the text-only tabs. They also allow for longer labels.
  • If you are using the icon tab bar in the object view floorplan, use either icon-only or text-only tabs.
    Icons only:
    Use this option if you have only 4-5 tabs that can be very clearly identified by their icon.
    Text only:
    Use this option if you have more than 4-5 tabs, or if there are no clear icons to represent the content. Set the property HeaderMode to “Inline”.
Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B. This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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 Side Content

Dynamic side content is a layout control that displays additional content to help the user better understand the data that’s being displayed on the screen.  It is displayed in a way that flexibly adapts to different screen sizes.

App development teams can configure the behavior of the control on smaller screen sizes by following the relevant guidelines.

Dynamic side content layout
Dynamic side content layout

Usage

Use dynamic side content if:

  • You want to display information that:
    • Will enrich the main content and will help the user better perform his/her tasks;
    • Only makes sense when displayed next to the main container (side-by-side);
    • Influences the main content (for example, a filter for list; settings for chart, details for map).
  • Users should have access to all of the key functions and critical information in the app even if they do not see the side content. This is important because on smaller screen sizes it may be difficult to display the side content in a way that is easily accessible for the user.

Do not use dynamic side content if:

  • You want to display critical information that should be visible all the time. The dynamic side content is not meant to split the page into two equally important sections.
  • You want to display navigation or drilldown. For drilldown scenarios, use the Flexible Column Layout.
  • You want to display a master-detail scenario. Instead, use the Flexible Column Layout.
Information
Currently Dynamic Side Content is not available in Fiori Elements.

Layout

Dynamic side content is displayed to the left or right of the main content container.

The dynamic side content can be closed by a button that is displayed in its toolbar.

The dynamic side content can be opened, if it set to hidden, with an action within the container to which it is directly related, or by an action displayed in the container-related toolbar, if it is available.

When the dynamic side content is displayed side-by-side to the container, it doesn’t overlay it. The main container narrows down and makes space for the additional content to be displayed.

  • Dynamic side content positioning
  • Dynamic side content positioning

Responsiveness

The dynamic side content control is built for different screen sizes and layouts.

Different sizes of dynamic side content

  • Dynamic side content - Size S
  • Dynamic side content - Size M
  • Dynamic side content - Size L

The default screen layout features the side content on the left or right side of the screen, covering 25% of the screen width on a large desktop (over 1440 px).

Dynamic side content - Default layout
Dynamic side content - Default layout

On smaller screen sizes (under 1440 px), the side content occupies 33% of the screen width to accommodate the nested controls. If the side content width falls below 320 px, the side content automatically slides under the main content, unless the app development team specifies that it should disappear.

Dynamic side content - smaller screen sizes
Dynamic side content - smaller screen sizes

On screen sizes of less than or equal to 720 px, the side content automatically disappears from the screen (unless specified to stay under the content) and can be triggered from a preset trigger (specified within the app). When the side content is triggered, it replaces the main content. We recommend that you always place the trigger for the side content in the same location, such as the container toolbar.

If only the side content is shown and the user increases the screen size, the main content is automatically displayed again. If the user then decreases the screen size, the side content disappears (unless specified to stay under the content), and can be opened again by the trigger.

Equal split: A special view of the side content is the 50:50 view, which enables users to show more data, for example, for comparison purposes. The responsive behavior of the equal split is the same as in the standard view: The side content disappears on screen widths of less than 720 px and can only be viewed by triggering it.

Dynamic side content - Equal split
Dynamic side content - Equal split

The app development team may specify that the side content should slide under the main content when the screen is resized to a smaller width. Sliding the side content under the main content on smaller screens allows it to remain on the screen at all times. However, it may only be accessible via scrolling.

Navigation

The side content is always related to the main content, so it must show content that can be triggered from the main content. This also means minimizing navigation, such as drill-ins within the side content, and displaying content that is triggered from the main content area. An example would be showing additional details such as contact information or conversation history. If a different type of data relates to the main content, app developers can implement a switcher in the side content. However, we recommend that you keep the side content free of additional navigation elements.

Triggering the side content

The side content can be set to hidden by default, and it automatically disappears when the screen width is less than or equal to 720 px (except when it is set to be under the main content).The app design team can define the trigger point. Our recommendation is to put a transparent text button with a meaningful label in the container toolbar, or an action inside the container the dynamic side content is related to. Ensure that the user can understand how to trigger the side content. Please, avoid using icons, because they can confuse the user.

Hiding the side content

The side content should be hidden from the header (top) section of the side content. The side content container itself has no header. We therefore strongly recommend that you use a toolbar control with a title, a transparent button labeled Close, and a spacer between them.

Hiding side content – From the header section
Hiding side content – From the header section

Guidelines

Dynamic Side Content in Object Page

Dynamic side content can be used within the object page. Use dynamic side content within a section if you want to give the user additional data related to this section. If you want to display additional information about the object such as a timeline, include this information as a new section.

Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page
Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page

Do not separate the screen into two panels. Do not use it for navigation, for drilldown, or for displaying information related to the entire object.

Dynamic Side Content in List Report

Do not separate the page into two panels when you are using it inside the list report. The dynamic side content should be placed directly next to the table or the chart container.

Do
Correct usage of dynamic side content in List Report
Correct usage of dynamic side content in List Report
Don't
Wrong usage of the dynamic side content in dynamic page
Wrong usage of the dynamic side content in dynamic page

Dynamic Side Content in Dynamic Page

Do not separate the page into two panels if you use dynamic side content within the dynamic page layout. Place the dynamic side content directly next to the page container and under the header container. The header snaps manually and both sections have their own scrollbars.

Do
Correct usage of dynamic side content in dynamic page
Correct usage of dynamic side content in dynamic page
Don't
Wrong usage of the dynamic side content in dynamic page
Wrong usage of the dynamic side content in dynamic page

Examples

Dynamic side content in object page, used with map
Dynamic side content in object page, used with map
Dynamic side content in object page, used with planning calendar
Dynamic side content in object page, used with planning calendar
Dynamic side content with event list
Dynamic side content with event list

Use of Controls in the Dynamic Side Content

You can use most of the main controls in the dynamic side content, such as text, simple form, chart, list, panel, tree, timeline, or feed and notes. However, you must make sure that the control doesn’t result in the appearance of a horizontal scrollbar.

Do not use complex controls, such as tables.

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

Form / Simple Form

Information
This article contains general design guidelines for all forms. The guidelines also apply for smart forms.

For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

Intro

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display only
Form control in display only
Mixed form with editable and non-editable fields
Mixed form with editable and non-editable fields
Developer Hint
The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms and simple forms. These should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field ratio 3:5:4
Form with a label-field ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form and simple form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form and simple form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms and simple forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – size M (3:5:4)
Form in full screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Column Layout

If you use the default form settings, each form group displays in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right of the screen.

To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns (layout: ColumnLayout).

You can use this option to distribute the content for up to two form groups. As soon as there are more than two form groups, the display reverts to the default layout (one column per form group).

The examples below show how forms with one and two form groups display with and without layout balancing.

One form group with default arrangement
One form group with default arrangement
One form group with balanced column layout
One form group with balanced column layout
Two form groups with default arrangement
Two form groups with default arrangement
Two form groups with balanced column layout
Two form groups with balanced column layout

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

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

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Label Alignment

  • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
  • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
Information
The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

Unit of Measurement

You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

Unit of Measurement
Unit of Measurement

Amount Alignment

When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

Label

To make it easier for users to differentiate between labels and values, labels in display-only mode are displayed in a different style to labels in edit mode.

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

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

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking or tapping the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show multiple facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • You plan to use only one single tab.

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Responsiveness – Icon tabs
Responsiveness – Icon tabs
Responsiveness – Text tabs
Responsiveness – Text tabs

In addition to the responsive overflow behavior, the icon tab bar can be forced into compact mode or even react dynamically to the application’s global density setting. See the Tab Density section for details.

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters next to the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels do not become too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure that the UpperCase property is disabled and that you enter the labels in title case (for example: Approval Flow).

Types – Text-only without counters
Types – Text-only without counters
Types – Text-only with inline counters
Types – Text-only with inline counters

Counters and Text Tabs

If counters are used, set the property HeaderMode to “Inline” so the counters appear in brackets after the labels.

Do not use the old layout that shows the counters on top of the labels (Headermode = “Standard”).

Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Types – Icons with counters
Types – Icons with counters

Please note that starting with SAPUI5 version 1.40, you should only use the horizontal type of label (icon and label side by side).

If your labels get truncated, consider using shorter labels or text tabs (without icons), since text tabs cannot get truncated.

Types – Icons with counters and labels
Types – Icons with counters and labels
Types – Icon-only
Types – Icon-only

Tabs as Filters

If you build the tab bar as a filter, it can comprise two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 189 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Types – Filter
Types – Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Types – Process
Types – Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Behavior and Interaction

Clicking/Tapping on a Tab

To navigate through the views, the user clicks or taps the tabs.

Optional behavior: If the user clicks or taps a tab that’s already open, the container collapses. It opens again when the user clicks any tab.

Use the expandable property to specify whether users can collapse the tab container (default = “true”):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the expandable property to “false”.

The expandable property controls the initial state of the container. Do not change the default state (“true”).

Changing the Order of Tabs

Applications can allow users to rearrange the tab order when working in a desktop environment (property: enableTabReordering). If this feature is enabled, users can use drag and drop to reorder tabs, either directly on the tab bar or inside the overflow menu. It is also possible to drag and drop tabs from the tab bar to the overflow menu and vice versa.

Please note that this feature is not available for tabs as process steps to ensure that consecutive steps do not get mixed up.

Interaction – Rearranging tabs
Interaction – Rearranging tabs
Interaction – Rearranging tabs in the overflow menu
Interaction – Rearranging tabs in the overflow menu
Interaction – Rearranging tabs between bar and overflow menu
Interaction – Rearranging tabs between bar and overflow menu

Styles

Tab Density

The default responsive design of the icon tab bar applies to both compact and cozy modes. However, in addition to this responsive behavior, the control can be forced into a compact mode, or even react dynamically to the application’s global density setting. This feature can be used to:

  • Save vertical space on the page (applies to both text and icon tabs)
  • Save horizontal space (icon tabs only; this is especially helpful when there are many tabs)
  • Generally use less space on mobile devices
  • Reduce noise when there are already more important visual elements on the screen (primarily icon tabs)

The property for the override is called tabDensityMode, which can be set to “Cozy”, “Compact”, or “Inherit”. “Cozy” is the default setting that renders the control in its regular dimensions. “Compact” reduces the control’s height and icon sizes (if applicable), even if there would be enough space for the cozy design. “Inherit” instructs the control to follow the global density mode defined for the application. For backward compatibility, the default setting is “Cozy”.

The following image shows some types of tabs with their default style (cozy, left) and the reduced density mode (compact, right).

Style – Tab density
Style – Tab density

Colors

The two different styles (round tabs and text only) are discussed in the Types section.

In both cases, you can use colors to give users additional orientation.

Information
Do not use colors for decoration only. Colors should always indicate a status that is relevant to the user.
When using colors, stick to the semantic colors provided by visual design. Do not hard-code color values. Instead, use the CSS extension “Less”.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors.

This example shows a process where one step is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles – Colors
Styles – Colors

Guidelines

Apply the styles as follows:

  • If you have only a few tabs that can easily be visualized with icons, use the icon-only tabs. If a short description is needed, use icons and labels.
  • If the content cannot easily be identified by an icon, use the text-only tabs. They also allow for longer labels.
  • If you are using the icon tab bar in the object view floorplan, use either icon-only or text-only tabs.
    Icons only:
    Use this option if you have only 4-5 tabs that can be very clearly identified by their icon.
    Text only:
    Use this option if you have more than 4-5 tabs, or if there are no clear icons to represent the content. Set the property HeaderMode to “Inline”.
Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B. This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Form / Simple Form

Information
This article contains general design guidelines for all forms. These guidelines also apply for smart forms.

For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

Intro

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display only
Form control in display only
Mixed form with editable and non-editable fields
Mixed form with editable and non-editable fields
Developer Hint
The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms and simple forms. These should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field ratio 3:5:4
Form with a label-field ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form and simple form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form and simple form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms and simple forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – size M (3:5:4)
Form in full screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Column Layout

If you use the default form settings, each form group displays in a separate column. Depending on the size of the form group, this can mean that users need to scroll down to see the full form, even though there is unused space on the right of the screen.

To make better use of screen space and give users a better overview without scrolling, you can balance form groups across multiple columns (layout: ColumnLayout).

You can use this option to distribute the content for up to two form groups. As soon as there are more than two form groups, the display reverts to the default layout (one column per form group).

The examples below show how forms with one and two form groups display with and without layout balancing.

One form group with default arrangement
One form group with default arrangement
One form group with balanced column layout
One form group with balanced column layout
Two form groups with default arrangement
Two form groups with default arrangement
Two form groups with balanced column layout
Two form groups with balanced column layout

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Label Alignment

  • We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
  • If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.
Information
The object page can show up to four columns if the screen is wide enough. In most cases, the space available per form column is too narrow to display the label next to the field/value. Because of this, forms within the multi-column layout of an object page only support labels above the fields values. Label lengths can vary greatly, and placing the labels on top reduces the risk of truncation for both the label and the content.

Unit of Measurement

You can add the unit of measurement after certain input controls by using the layout options of the form. Examples of supported input controls include multi-input field, select, combo box, multi combo box, and mask input.

If you display the unit of measurement after the input control, make sure that it’s properly visualized and doesn’t wrap to the next row.

Unit of Measurement
Unit of Measurement

Label

To make it easier for users to differentiate between labels and values, labels in display-only mode are displayed in a different style to labels in edit mode.

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

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 Side Content

Dynamic side content is a layout control that displays additional content to help the user better understand the data that’s being displayed on the screen.  It is displayed in a way that flexibly adapts to different screen sizes.

App development teams can configure the behavior of the control on smaller screen sizes by following the relevant guidelines.

Dynamic side content layout
Dynamic side content layout

Usage

Use dynamic side content if:

  • You want to display information that:
    • Will enrich the main content and will help the user better perform his/her tasks;
    • Only makes sense when displayed next to the main container (side-by-side);
    • Influences the main content (for example, a filter for list; settings for chart, details for map).
  • Users should have access to all of the key functions and critical information in the app even if they do not see the side content. This is important because on smaller screen sizes it may be difficult to display the side content in a way that is easily accessible for the user.

Do not use dynamic side content if:

  • You want to display critical information that should be visible all the time. The dynamic side content is not meant to split the page into two equally important sections.
  • You want to display navigation or drilldown. For drilldown scenarios, use the Flexible Column Layout.
  • You want to display a master-detail scenario. Instead, use the Flexible Column Layout.
Information
Currently Dynamic Side Content is not available in Fiori Elements.

Layout

Dynamic side content is displayed to the left or right of the main content container.

The dynamic side content can be closed by a button that is displayed in its toolbar.

The dynamic side content can be opened, if it set to hidden, with an action within the container to which it is directly related, or by an action displayed in the container-related toolbar, if it is available.

When the dynamic side content is displayed side-by-side to the container, it doesn’t overlay it. The main container narrows down and makes space for the additional content to be displayed.

  • Dynamic side content positioning
  • Dynamic side content positioning

Responsiveness

The dynamic side content control is built for different screen sizes and layouts.

Different sizes of dynamic side content

  • Dynamic side content - Size S
  • Dynamic side content - Size M
  • Dynamic side content - Size L

The default screen layout features the side content on the left or right side of the screen, covering 25% of the screen width on a large desktop (over 1440 px).

Dynamic side content - Default layout
Dynamic side content - Default layout

On smaller screen sizes (under 1440 px), the side content occupies 33% of the screen width to accommodate the nested controls. If the side content width falls below 320 px, the side content automatically slides under the main content, unless the app development team specifies that it should disappear.

Dynamic side content - smaller screen sizes
Dynamic side content - smaller screen sizes

On screen sizes of less than or equal to 720 px, the side content automatically disappears from the screen (unless specified to stay under the content) and can be triggered from a preset trigger (specified within the app). When the side content is triggered, it replaces the main content. We recommend that you always place the trigger for the side content in the same location, such as in the container toolbar.

Equal split: A special view of the side content is the 50:50 view, which enables users to show more data, for example, for comparison purposes. The responsive behavior of the equal split is the same as in the standard view: The side content disappears on screen widths of less than 720 px and can only be viewed by triggering it.

Dynamic side content - Equal split
Dynamic side content - Equal split

The app development team may specify that the side content should slide under the main content when the screen is resized to a smaller width. Sliding the side content under the main content on smaller screens allows it to remain on the screen at all times. However, it may only be accessible via scrolling.

Navigation

The side content is always related to the main content, so it must show content that can be triggered from the main content. This also means minimizing navigation, such as drill-ins within the side content, and displaying content that is triggered from the main content area. An example would be showing additional details such as contact information or conversation history. If a different type of data relates to the main content, app developers can implement a switcher in the side content. However, we recommend that you keep the side content free of additional navigation elements.

Triggering the side content

The side content can be set to hidden by default, and it automatically disappears when the screen width is less than or equal to 720 px (except when it is set to be under the main content).The app design team can define the trigger point. Our recommendation is to put a transparent text button with a meaningful label in the container toolbar, or an action inside the container the dynamic side content is related to. Ensure that the user can understand how to trigger the side content. Please, avoid using icons, because they can confuse the user.

Hiding the side content

The side content should be hidden from the header (top) section of the side content. The side content container itself has no header. We therefore strongly recommend that you use a toolbar control with a title, a transparent button labeled Close, and a spacer between them.

Hiding side content – From the header section
Hiding side content – From the header section

Guidelines

Dynamic Side Content in Object Page

Dynamic side content can be used within the object page. Use dynamic side content within a section if you want to give the user additional data related to this section. If you want to display additional information about the object such as a timeline, include this information as a new section.

Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page
Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page

Do not separate the screen into two panels. Do not use it for navigation, for drilldown, or for displaying information related to the entire object.

Dynamic Side Content in List Report

Do not separate the page into two panels when you are using it inside the list report. The dynamic side content should be placed directly next to the table or the chart container.

Do
Correct usage of dynamic side content in List Report
Correct usage of dynamic side content in List Report
Don't
Wrong usage of the dynamic side content in dynamic page
Wrong usage of the dynamic side content in dynamic page

Dynamic Side Content in Dynamic Page

Do not separate the page into two panels if you use dynamic side content within the dynamic page layout. Place the dynamic side content directly next to the page container and under the header container. The header snaps manually and both sections have their own scrollbars.

Do
Correct usage of dynamic side content in dynamic page
Correct usage of dynamic side content in dynamic page
Don't
Wrong usage of the dynamic side content in dynamic page
Wrong usage of the dynamic side content in dynamic page

Examples

Dynamic side content in object page, used with map
Dynamic side content in object page, used with map
Dynamic side content in object page, used with planning calendar
Dynamic side content in object page, used with planning calendar
Dynamic side content with event list
Dynamic side content with event list

Use of Controls in the Dynamic Side Content

You can use most of the main controls in the dynamic side content, such as text, simple form, chart, list, panel, tree, timeline, or feed and notes. However, you must make sure that the control doesn’t result in the appearance of a horizontal scrollbar.

Do not use complex controls, such as tables.

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

Form / Simple Form

Information
This article contains general design guidelines for all forms. These guidelines also apply for smart forms.

For additional hints on smart forms, you can still refer to the existing Forms / Simple Forms / Smart Forms article for guideline version 1.52. However, please note that this page is no longer updated.

Intro

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display only
Form control in display only
Mixed form with editable and non-editable fields
Mixed form with editable and non-editable fields
Developer Hint
The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.
Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms and simple forms. These should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field ratio 3:5:4
Form with a label-field ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form and simple form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form and simple form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms and simple forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – size M (3:5:4)
Form in full screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Label

To make it easier for users to differentiate between labels and values, labels in display-only mode are displayed in a different style to labels in edit mode.

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

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

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking or tapping the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show multiple facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • You plan to use only one single tab.

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Responsiveness – Icon tabs
Responsiveness – Icon tabs
Responsiveness – Text tabs
Responsiveness – Text tabs

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters next to the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels do not become too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure that the UpperCase property is disabled and that you enter the labels in title case (for example: Approval Flow).

Types – Text-only without counters
Types – Text-only without counters
Types – Text-only with inline counters
Types – Text-only with inline counters

Counters and Text Tabs

If counters are used, set the property HeaderMode to “Inline” so the counters appear in brackets after the labels.

Do not use the old layout that shows the counters on top of the labels (Headermode = “Standard”).

Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Types – Icons with counters
Types – Icons with counters

Please note that starting with SAPUI5 version 1.40, you should only use the horizontal type of label (icon and label side by side).

If your labels get truncated, consider using shorter labels or text tabs (without icons), since text tabs cannot get truncated.

Types – Icons with counters and labels
Types – Icons with counters and labels
Types – Icon-only
Types – Icon-only

Tabs as Filters

If you build the tab bar as a filter, it can comprise two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 189 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Types – Filter
Types – Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Types – Process
Types – Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Behavior and Interaction

Clicking/Tapping on a Tab

To navigate through the views, the user clicks or taps the tabs.

Optional behavior: If the user clicks or taps a tab that’s already open, the container collapses. It opens again when the user clicks any tab.

Use the expandable property to specify whether users can collapse the tab container (default = “true”):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the expandable property to “false”.

The expandable property controls the initial state of the container. Do not change the default state (“true”).

Changing the Order of Tabs

Applications can allow users to rearrange the tab order when working in a desktop environment (property: enableTabReordering). If this feature is enabled, users can use drag and drop to reorder tabs, either directly on the tab bar or inside the overflow menu.

Please note that this feature is not available for tabs as process steps to ensure that consecutive steps do not get mixed up.

Interaction – Rearranging tabs
Interaction – Rearranging tabs
Interaction – Rearranging tabs in the overflow menu
Interaction – Rearranging tabs in the overflow menu

Styles

The two different styles (round tabs and text only) are discussed in the Types section.

In both cases, you can use colors to give users additional orientation.

Information
Do not use colors for decoration only. Colors should always indicate a status that is relevant to the user.
When using colors, stick to the semantic colors provided by visual design. Do not hard-code color values. Instead, use the CSS extension “Less”.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors.

This example shows a process where one step is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles – Colors
Styles – Colors

Guidelines

Apply the styles as follows:

  • If you have only a few tabs that can easily be visualized with icons, use the icon-only tabs. If a short description is needed, use icons and labels.
  • If the content cannot easily be identified by an icon, use the text-only tabs. They also allow for longer labels.
  • If you are using the icon tab bar in the object view floorplan, use either icon-only or text-only tabs.
    Icons only:
    Use this option if you have only 4-5 tabs that can be very clearly identified by their icon.
    Text only:
    Use this option if you have more than 4-5 tabs, or if there are no clear icons to represent the content. Set the property HeaderMode to “Inline”.
Do
Counters – Inline layout ('HeaderMode' set to 'Inline')
Counters – Inline layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old layout ('HeaderMode' set to 'Standard')
Counters – Old layout ('HeaderMode' set to 'Standard')

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B. This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Block Layout

Information

This layout has been designed specifically for the tool landscape for the SAP Cloud Platform. It is not intended for use in regular SAP Fiori applications. 

Intro

The block layout is used to display content in a section-based manner. It features horizontal and vertical subdivisions and full-width banners seen frequently in contemporary Web design. Background colors are attached directly to these areas within the layout. As well, special full-width sections of the block layout enable horizontal scrolling through a set of areas.

General page structure of a tool using the block layout
General page structure of a tool using the block layout
Block layout standalone
Block layout standalone

Usage

Example use cases include landing pages and catalog-like pages. In landing pages, the block layout may serve as a banner-like presentation of illustrative icons with associated text. By placing pictorial and textual elements side by side in different areas, a content relationship is established. In catalog-like layouts, the block layout serves as a flexible container for diverging content, such as headings, explanatory texts, code snippets, remarks, and examples.

It is also possible to have clickable blocks with their own hover and pressed states.

There are four types of block layout: layout only (default), light, and accent background colors, as well as a variant for dashboard pages.

Schematic block layout
Schematic block layout
Schematic block layout with a section scrolling horizontally
Schematic block layout with a section scrolling horizontally

Use the block layout if:

  • You want to display section-based content. Place elements next to each other to indicate a content relationship.
  • You want to display KPIs in the dashboard-variant. Do not use other variants for KPIs.

Do not use the block layout if:

  • You want to display properties or features of one content item. Use the object page floorplan instead. Links within a block must lead to areas outside of the block. As well, enable controls to update only their own containers and not other containers.

Layout

The block layout is divided into horizontal sections, which take on the full width of the available screen real estate. Their screen height is determined by their inner content, which prevents vertical scrolling. If needed, the width of sections can also be set to the following predefined ratios (for the sizes XL, L and M):

  • 1 block: 100%
  • 2 blocks: 75% and 25% / 25% and 75%
  • 2 blocks: 50% and 50%
  • 3 blocks: 2 × 25% and 50% / 50% and 2 × 25% / 25% and 50% and 25%
  • 3 blocks: 3 × 33%
  • 4 blocks: 4 × 25%

Horizontal scrolling sections always have a width of 100%.

Responsiveness

The block layout offers responsive behavior. There are three breakpoints, which results in four supported sizes: XL, L, M, and S. As with the responsive grid (another generic layout control), these breakpoints apply both to the page and block layout. However, the page layout’s breakpoints react to screen width, whereas the breakpoints of the block layout react to the width of the control itself.

Ratios of areas in different contexts

Blocks per section XL, L M S
1 100%  100% 100%
2 75% and 25%
25% and 75%		 75% and 25%
or
25% and 75%		 100% each*
100% each*
2 50% and 50%  50% and 50% 100% each*
3 2 × 25% and 50%
50% and 2 × 25%
25% and 50% and 25%		 2 x 50% and 100% over two rows
or
100% and 2 x 50% over two rows		 100% each*
100% each*
100% each*
3 3 × 33%  3 x 33% 100% each*
4 4 × 25%  2 x 50% over two rows 100% each*

*Blocks wrap and are displayed underneath each other

Responsive behavior of sections and areas
Responsive behavior of sections and areas
Responsive behavior of sections and areas
Responsive behavior of sections and areas
Responsive behavior of a section with horizontal scrolling
Responsive behavior of a section with horizontal scrolling

The width of the horizontal scrolling area in different device contexts

XL, L M S
22.5% or 40% depending on the number of areas
3 to 5 areas: 40%
6 to 10 areas: 22.5%		 40% 90%

Types

There are four types of block layouts:

  1. Default: This layout does not use any background colors.
  2. Light: Areas use predefined colors found in the SAP Fiori 2.0 visual design language. These colors follow a specific order specified in the control. If there are more than four areas, the background colors start over from the initial color.
  3. Accent: Each row contains a range of colors derived from one accent color, and these colors are used alternately. If required by the control, you can display multiple gray blocks: the different shades of gray will then be displayed alternately, beginning with the initial color.
  4. Dashboard: This layout type uses spacing around the blocks. It is mainly used for applications that display charts in the blocks.

Colors

Cell Colors

Colors can be set for each individual cell. There are 10 pre-defined color sets, each with 4 different shades. To change the background of a particular cell, set the block layout’s background color set (main color) (property: backgroundColorSet) and background color shade (shade) (property: backgroundColorSet) accordingly.

The available colors are shown below.

Available Colors

Color set 1, with shades A to D
Color set 1, with shades A to D
Color set 3, with shades A to D
Color set 3, with shades A to D
Color set 5, with shades A to D
Color set 5, with shades A to D
Color set 7, with shades A to D
Color set 7, with shades A to D
Color set 9, with shades A to D
Color set 9, with shades A to D
Color set 2, with shades A to D
Color set 2, with shades A to D
Color set 4, with shades A to D
Color set 4, with shades A to D
Color set 6, with shades A to D
Color set 6, with shades A to D
Color set 8, with shades A to D
Color set 8, with shades A to D
Color set 10, with shades A to D
Color set 10, with shades A to D

Row Color Sets

For rows in the “Light” and the “Accent” variant of the block layout, you may choose between different row color sets (property:rowColorSet). These sets enable different starting colors for the row coloring, preventing color coalescence in the responsive behavior of the block layout.

Images

Images may be placed as background images within one block. The predefined paddings do not apply to blocks with images; images are displayed in the entire block.
If needed, the title control may be placed above the images.

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 Side Content

Dynamic side content is a layout control that displays additional content to help the user better understand the data that’s being displayed on the screen.  It is displayed in a way that flexibly adapts to different screen sizes.

App development teams can configure the behavior of the control on smaller screen sizes by following the relevant guidelines.

Dynamic side content layout
Dynamic side content layout

Usage

Use dynamic side content if:

  • You want to display information that:
    • Will enrich the main content and will help the user better perform his/her tasks;
    • Only makes sense when displayed next to the main container (side-by-side);
    • Influences the main content (for example, a filter for list; settings for chart, details for map).
  • Users should have access to all of the key functions and critical information in the app even if they do not see the side content. This is important because on smaller screen sizes it may be difficult to display the side content in a way that is easily accessible for the user.

Do not use dynamic side content if:

  • You want to display critical information that should be visible all the time. The dynamic side content is not meant to split the page into two equally important sections.
  • You want to display navigation or drilldown. For drilldown scenarios, use the Flexible Column Layout.
  • You want to display a master-detail scenario. Instead, use the Flexible Column Layout.
Information
Currently Dynamic Side Content is not available in Fiori Elements.

Layout

Dynamic side content is displayed to the left or right of the main content container.

The dynamic side content can be closed by a button that is displayed in its toolbar.

The dynamic side content can be opened, if it set to hidden, with an action within the container to which it is directly related, or by an action displayed in the container-related toolbar, if it is available.

When the dynamic side content is displayed side-by-side to the container, it doesn’t overlay it. The main container narrows down and makes space for the additional content to be displayed.

  • Dynamic side content positioning
  • Dynamic side content positioning

Responsiveness

The dynamic side content control is built for different screen sizes and layouts.

Different sizes of dynamic side content

  • Dynamic side content - Size S
  • Dynamic side content - Size M
  • Dynamic side content - Size L

The default screen layout features the side content on the left or right side of the screen, covering 25% of the screen width on a large desktop (over 1440 px).

Dynamic side content - Default layout
Dynamic side content - Default layout

On smaller screen sizes (under 1440 px), the side content occupies 33% of the screen width to accommodate the nested controls. If the side content width falls below 320 px, the side content automatically slides under the main content, unless the app development team specifies that it should disappear.

Dynamic side content - smaller screen sizes
Dynamic side content - smaller screen sizes

On screen sizes of less than or equal to 720 px, the side content automatically disappears from the screen (unless specified to stay under the content) and can be triggered from a preset trigger (specified within the app). When the side content is triggered, it replaces the main content. We recommend that you always place the trigger for the side content in the same location, such as in the container toolbar.

Equal split: A special view of the side content is the 50:50 view, which enables users to show more data, for example, for comparison purposes. The responsive behavior of the equal split is the same as in the standard view: The side content disappears on screen widths of less than 720 px and can only be viewed by triggering it.

Dynamic side content - Equal split
Dynamic side content - Equal split

The app development team may specify that the side content should slide under the main content when the screen is resized to a smaller width. Sliding the side content under the main content on smaller screens allows it to remain on the screen at all times. However, it may only be accessible via scrolling.

Navigation

The side content is always related to the main content, so it must show content that can be triggered from the main content. This also means minimizing navigation, such as drill-ins within the side content, and displaying content that is triggered from the main content area. An example would be showing additional details such as contact information or conversation history. If a different type of data relates to the main content, app developers can implement a switcher in the side content. However, we recommend that you keep the side content free of additional navigation elements.

Triggering the side content

The side content can be set to hidden by default, and it automatically disappears when the screen width is less than or equal to 720 px (except when it is set to be under the main content).The app design team can define the trigger point. Our recommendation is to put a transparent text button with a meaningful label in the container toolbar, or an action inside the container the dynamic side content is related to. Ensure that the user can understand how to trigger the side content. Please, avoid using icons, because they can confuse the user.

Hiding the side content

The side content should be hidden from the header (top) section of the side content. The side content container itself has no header. We therefore strongly recommend that you use a toolbar control with a title, a transparent button labeled Close, and a spacer between them.

Hiding side content – From the header section
Hiding side content – From the header section

Guidelines

Dynamic Side Content in Object Page

Dynamic side content can be used within the object page. Use dynamic side content within a section if you want to give the user additional data related to this section. If you want to display additional information about the object such as a timeline, include this information as a new section.

Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page
Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page

Do not separate the screen into two panels. Do not use it for navigation, for drilldown, or for displaying information related to the entire object.

Dynamic Side Content in List Report

Do not separate the page into two panels when you are using it inside the list report. The dynamic side content should be placed directly next to the table or the chart container.

Do
Correct usage of dynamic side content in List Report
Correct usage of dynamic side content in List Report
Don't
Wrong usage of the dynamic side content in dynamic page
Wrong usage of the dynamic side content in dynamic page

Dynamic Side Content in Dynamic Page

Do not separate the page into two panels if you use dynamic side content within the dynamic page layout. Place the dynamic side content directly next to the page container and under the header container. The header snaps manually and both sections have their own scrollbars.

Do
Correct usage of dynamic side content in dynamic page
Correct usage of dynamic side content in dynamic page
Don't
Wrong usage of the dynamic side content in dynamic page
Wrong usage of the dynamic side content in dynamic page

Examples

Dynamic side content in object page, used with map
Dynamic side content in object page, used with map
Dynamic side content in object page, used with planning calendar
Dynamic side content in object page, used with planning calendar
Dynamic side content with event list
Dynamic side content with event list

Use of Controls in the Dynamic Side Content

You can use most of the main controls in the dynamic side content, such as text, simple form, chart, list, panel, tree, timeline, or feed and notes. However, you must make sure that the control doesn’t result in the appearance of a horizontal scrollbar.

Do not use complex controls, such as tables.

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

Form / Simple Form / Smart Form

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using three different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

The smart form control belongs to the new set of smart controls. Smart controls give developers the possibility to build UIs without the need to build a complex UI code (the term “smart” refers to the annotations that add semantics and structures to the provided data). The goals are to ensure design consistency, keep apps up to date with evolving design guidelines, and reduce the amount of front-end code for building SAP Fiori apps. Compared to the corresponding standard controls, however, the settings may be limited.

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display only
Form control in display only
Mixed form with editable and non-editable fields
Mixed form with editable and non-editable fields
Developer Hint
The smart form property editable really switches the smart form between edit mode and read-only mode. For example, fields become texts and vice versa.

The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.

Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field ratio 3:5:4
Form with a label-field ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form, simple form, and smart form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form, simple form, and smart form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms, simple forms, and smart forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – size M (3:5:4)
Form in full screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Label

To make it easier for users to differentiate between labels and values, labels in display-only mode are displayed in a different style to labels in edit mode.

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

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

Block Layout

Information

This layout has been designed specifically for the tool landscape for SAP HANA Cloud Platform. It is not intended for use in regular SAP Fiori applications. 

Intro

The block layout is used to display content in a section-based manner. It features horizontal and vertical subdivisions and full-width banners seen frequently in contemporary Web design. Background colors are attached directly to these areas within the layout. As well, special full-width sections of the block layout enable horizontal scrolling through a set of areas.

General page structure of a tool using the block layout
General page structure of a tool using the block layout
Block layout standalone
Block layout standalone

Usage

Example use cases include landing pages and catalog-like pages. In landing pages, the block layout may serve as a banner-like presentation of illustrative icons with associated text. By placing pictorial and textual elements side by side in different areas, a content relationship is established. In catalog-like layouts, the block layout serves as a flexible container for diverging content, such as headings, explanatory texts, code snippets, remarks, and examples.

It is also possible to have clickable blocks with their own hover and pressed states.

There are four types of block layout: layout only (default), light, and accent background colors, as well as a variant for dashboard pages.

Schematic block layout
Schematic block layout
Schematic block layout with a section scrolling horizontally
Schematic block layout with a section scrolling horizontally

Use the block layout if:

  • You want to display section-based content. Place elements next to each other to indicate a content relationship.
  • You want to display KPIs in the dashboard-variant. Do not use other variants for KPIs.

Do not use the block layout if:

  • You want to display properties or features of one content item. Use the object page floorplan instead. Links within a block must lead to areas outside of the block. As well, enable controls to update only their own containers and not other containers.

Layout

The block layout is divided into horizontal sections, which take on the full width of the available screen real estate. Their screen height is determined by their inner content, which prevents vertical scrolling. If needed, the width of sections can also be set to the following predefined ratios (for the sizes XL, L and M):

  • 1 block: 100%
  • 2 blocks: 75% and 25% / 25% and 75%
  • 2 blocks: 50% and 50%
  • 3 blocks: 2 × 25% and 50% / 50% and 2 × 25% / 25% and 50% and 25%
  • 3 blocks: 3 × 33%
  • 4 blocks: 4 × 25%

Horizontal scrolling sections always have a width of 100%.

Responsiveness

The block layout offers responsive behavior. There are three breakpoints, which results in four supported sizes: XL, L, M, and S. As with the responsive grid (another generic layout control), these breakpoints apply both to the page and block layout. However, the page layout’s breakpoints react to screen width, whereas the breakpoints of the block layout react to the width of the control itself.

Ratios of areas in different contexts

Blocks per section XL, L M S
1 100%  100% 100%
2 75% and 25%
25% and 75%		 75% and 25%
or
25% and 75%		 100% each*
100% each*
2 50% and 50%  50% and 50% 100% each*
3 2 × 25% and 50%
50% and 2 × 25%
25% and 50% and 25%		 2 x 50% and 100% over two rows
or
100% and 2 x 50% over two rows		 100% each*
100% each*
100% each*
3 3 × 33%  3 x 33% 100% each*
4 4 × 25%  2 x 50% over two rows 100% each*

*Blocks wrap and are displayed underneath each other

Responsive behavior of sections and areas
Responsive behavior of sections and areas
Responsive behavior of sections and areas
Responsive behavior of sections and areas
Responsive behavior of a section with horizontal scrolling
Responsive behavior of a section with horizontal scrolling

The width of the horizontal scrolling area in different device contexts

XL, L M S
22.5% or 40% depending on the number of areas
3 to 5 areas: 40%
6 to 10 areas: 22.5%		 40% 90%

Types

There are four types of block layouts:

  1. Default: This layout does not use any background colors.
  2. Light: Areas use predefined colors found in the SAP Fiori 2.0 visual design language. These colors follow a specific order specified in the control. If there are more than four areas, the background colors start over from the initial color.
  3. Accent: Each row contains a range of colors derived from one accent color, and these colors are used alternately. If required by the control, you can display multiple gray blocks: the different shades of gray will then be displayed alternately, beginning with the initial color.
  4. Dashboard: This layout type uses spacing around the blocks. It is mainly used for applications that display charts in the blocks.

Colors

Cell Colors

Colors can be set for each individual cell. There are 10 pre-defined color sets, each with 4 different shades. To change the background of a particular cell, set the block layout’s background color set (main color) (property: backgroundColorSet) and background color shade (shade) (property: backgroundColorSet) accordingly.

The available colors are shown below.

Available Colors

Color set 1, with shades A to D
Color set 1, with shades A to D
Color set 3, with shades A to D
Color set 3, with shades A to D
Color set 5, with shades A to D
Color set 5, with shades A to D
Color set 7, with shades A to D
Color set 7, with shades A to D
Color set 9, with shades A to D
Color set 9, with shades A to D
Color set 2, with shades A to D
Color set 2, with shades A to D
Color set 4, with shades A to D
Color set 4, with shades A to D
Color set 6, with shades A to D
Color set 6, with shades A to D
Color set 8, with shades A to D
Color set 8, with shades A to D
Color set 10, with shades A to D
Color set 10, with shades A to D

Row Color Sets

For rows in the “Light” and the “Accent” variant of the block layout, you may choose between different row color sets (property:rowColorSet). These sets enable different starting colors for the row coloring, preventing color coalescence in the responsive behavior of the block layout.

Images

Images may be placed as background images within one block. The predefined paddings do not apply to blocks with images; images are displayed in the entire block.
If needed, the title control may be placed above the images.

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

Form / Simple Form / Smart Form

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using three different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

The smart form control belongs to the new set of smart controls. Smart controls give developers the possibility to build UIs without the need to build a complex UI code (the term “smart” refers to the annotations that add semantics and structures to the provided data). The goals are to ensure design consistency, keep apps up to date with evolving design guidelines, and reduce the amount of front-end code for building SAP Fiori apps. Compared to the corresponding standard controls, however, the settings may be limited.

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display only
Form control in display only
Mixed form with editable and non-editable fields
Mixed form with editable and non-editable fields
Developer Hint
The smart form property editable really switches the smart form between edit mode and read-only mode. For example, fields become texts and vice versa.

The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.

Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field-ratio 3:5:4
Form with a label-field-ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form, simple form, and smart form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form, simple form, and smart form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms, simple forms, and smart forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – size M (3:5:4)
Form in full screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the style sheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

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 Side Content

Dynamic side content is a layout control that displays additional content to help the user better understand the data that’s being displayed on the screen.  It is displayed in a way that flexibly adapts to different screen sizes.

App development teams can configure the behavior of the control on smaller screen sizes by following the relevant guidelines.

Dynamic side content layout
Dynamic side content layout

Usage

Use dynamic side content if:

  • You want to display information that:
    • Will enrich the main content and will help the user better perform his/her tasks;
    • Only makes sense when displayed next to the main container (side-by-side);
    • Influences the main content (for example, a filter for list; settings for chart, details for map).
  • Users should have access to all of the key functions and critical information in the app even if they do not see the side content. This is important because on smaller screen sizes it may be difficult to display the side content in a way that is easily accessible for the user.

Do not use dynamic side content if:

  • You want to display critical information that should be visible all the time. The dynamic side content is not meant to split the page into two equally important sections.
  • You want to display navigation or drilldown. For drilldown scenarios, use the Flexible Column Layout.
  • You want to display a master-detail scenario. Instead, use the Flexible Column Layout.
Information
Currently Dynamic Side Content is not available in Fiori Elements.

Layout

Dynamic side content is displayed to the left or right of the main content container.

The dynamic side content can be closed by a button that is displayed in its toolbar.

The dynamic side content can be opened, if it set to hidden, with an action within the container to which it is directly related, or by an action displayed in the container-related toolbar, if it is available.

When the dynamic side content is displayed side-by-side to the container, it doesn’t overlay it. The main container narrows down and makes space for the additional content to be displayed.

  • Dynamic side content positioning
  • Dynamic side content positioning

Responsiveness

The dynamic side content control is built for different screen sizes and layouts.

Different sizes of dynamic side content

  • Dynamic side content - Size S
  • Dynamic side content - Size M
  • Dynamic side content - Size L

The default screen layout features the side content on the left or right side of the screen, covering 25% of the screen width on a large desktop (over 1440 px).

Dynamic side content - Default layout
Dynamic side content - Default layout

On smaller screen sizes (under 1440 px), the side content occupies 33% of the screen width to accommodate the nested controls. If the side content width falls below 320 px, the side content automatically slides under the main content, unless the app development team specifies that it should disappear.

Dynamic side content - smaller screen sizes
Dynamic side content - smaller screen sizes

On screen sizes of less than or equal to 720 px, the side content automatically disappears from the screen (unless specified to stay under the content) and can be triggered from a preset trigger (specified within the app). When the side content is triggered, it replaces the main content. We recommend that you always place the trigger for the side content in the same location, such as in the container toolbar.

Equal split: A special view of the side content is the 50:50 view, which enables users to show more data, for example, for comparison purposes. The responsive behavior of the equal split is the same as in the standard view: The side content disappears on screen widths of less than 720 px and can only be viewed by triggering it.

Dynamic side content - Equal split
Dynamic side content - Equal split

The app development team may specify that the side content should slide under the main content when the screen is resized to a smaller width. Sliding the side content under the main content on smaller screens allows it to remain on the screen at all times. However, it may only be accessible via scrolling.

Navigation

The side content is always related to the main content, so it must show content that can be triggered from the main content. This also means minimizing navigation, such as drill-ins within the side content, and displaying content that is triggered from the main content area. An example would be showing additional details such as contact information or conversation history. If a different type of data relates to the main content, app developers can implement a switcher in the side content. However, we recommend that you keep the side content free of additional navigation elements.

Triggering the side content

The side content can be set to hidden by default, and it automatically disappears when the screen width is less than or equal to 720 px (except when it is set to be under the main content).The app design team can define the trigger point. Our recommendation is to put a transparent text button with a meaningful label in the container toolbar, or an action inside the container the dynamic side content is related to. Ensure that the user can understand how to trigger the side content. Please, avoid using icons, because they can confuse the user.

Hiding the side content

The side content should be hidden from the header (top) section of the side content. The side content container itself has no header. We therefore strongly recommend that you use a toolbar control with a title, a transparent button labeled Close, and a spacer between them.

Hiding side content – From the header section
Hiding side content – From the header section

Guidelines

Dynamic Side Content in Object Page

Dynamic side content can be used within the object page. Use dynamic side content within a section if you want to give the user additional data related to this section. If you want to display additional information about the object such as a timeline, include this information as a new section.

Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page
Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page

Do not separate the screen into two panels. Do not use it for navigation, for drilldown, or for displaying information related to the entire object.

Dynamic Side Content in List Report

Do not separate the page into two panels when you are using it inside the list report. The dynamic side content should be placed directly next to the table or the chart container.

Do
Correct usage of dynamic side content in List Report
Correct usage of dynamic side content in List Report
Don't
Wrong usage of the dynamic side content in dynamic page
Wrong usage of the dynamic side content in dynamic page

Dynamic Side Content in Dynamic Page

Do not separate the page into two panels if you use dynamic side content within the dynamic page layout. Place the dynamic side content directly next to the page container and under the header container. The header snaps manually and both sections have their own scrollbars.

Do
Correct usage of dynamic side content in dynamic page
Correct usage of dynamic side content in dynamic page
Don't
Wrong usage of the dynamic side content in dynamic page
Wrong usage of the dynamic side content in dynamic page

Examples

Dynamic side content in object page, used with map
Dynamic side content in object page, used with map
Dynamic side content in object page, used with planning calendar
Dynamic side content in object page, used with planning calendar
Dynamic side content with event list
Dynamic side content with event list

Use of Controls in the Dynamic Side Content

You can use most of the main controls in the dynamic side content, such as text, simple form, chart, list, panel, tree, timeline, or feed and notes. However, you must make sure that the control doesn’t result in the appearance of a horizontal scrollbar.

Do not use complex controls, such as tables.

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

Carousel

The carousel allows the user to browse through a set of items. It always displays one item at a time. From the displayed item, the user can navigate to either the next or the previous item. The interaction is similar to browsing through the pages of a book.

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

The carousel control is best used for browsing through a set of images. Viewing images one by one helps users to distinguish between different items. However, the carousel is not limited to displaying images; it can contain any sap.m control.

Usage

Use the carousel if:

  • You have strong visual representations of the items you want to display.
  • You want to display the items one after the other.

Do not use the carousel if:

  • The items you want to display are uniform.
  • The items you want to display need to be visible at the same time.

Responsiveness

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

On non-touch devices, the user can navigate with Previous and Next icons displayed on the left and right of the control.

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

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

Carousel - Size S
Carousel - Size S

Carousel - Size M
Carousel - Size M

Carousel - Size L
Carousel - Size L

Layout

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

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

On non-touch devices, icons for navigating to the next or previous item either float above the left and right sides of the content area, or appear in the paging indicator area. This is controlled by the arrowsPlacement property.

Schematic layout of the carousel
Schematic layout of the carousel

Behavior and Interaction

The current item is displayed in the content area.

Navigating

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

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

On non-touch devices, users navigate with icons.

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

Navigation – Previous
Navigation – Previous
Navigation – Next (hover)
Navigation – Next (hover)

Looping

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

Paging

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

Paging indicator
Paging indicator

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

Paging indicator
Paging indicator

Resources

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

Elements and Controls

Image (guidelines)

Implementation

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking or tapping the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show many facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • An object type has only one tab in the entire app.
    In this case, we recommend removing the icon tab bar and placing the content on the same level as the object header. To replace the tab label, add a headline with the same text (for example, Information).

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Responsiveness - Icon tabs
Responsiveness - Icon tabs
Responsiveness - Text tabs
Responsiveness - Text tabs

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters above the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels do not become too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure that the property UpperCase is disabled and that you enter the labels in title case (Example: Approval Flow).

Types ─ Text-only without counters
Types ─ Text-only without counters
Types ─ Text-only with inline counters
Types ─ Text-only with inline counters

Counters and Text Tabs

If counters are used, set the property HeaderMode to Inline so the counters appear in brackets after the labels.

Please do not use the old layout that shows the counters on top of the labels (Headermode = Standard).

Do
Counters – Inline Layout ('HeaderMode' set to 'Inline')
Counters – Inline Layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old Layout ('HeaderMode' set to 'Standard')
Counters – Old Layout ('HeaderMode' set to 'Standard')

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Types - Icons with counters
Types - Icons with counters

Please note that starting with SAPUI5 version 1.40, you should only use the horizontal type of label (icon and label side by side).

If your labels get truncated, consider using shorter labels or text tabs (without icons), as text tabs cannot get truncated.

Types - Icons with counters and labels
Types - Icons with counters and labels
Types - Icon-only
Types - Icon-only

Tabs as Filters

If you build the tab bar as a filter, it can comprise two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 189 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Types - Filter
Types - Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Types - Process
Types - Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Behavior and Interaction

Clicking/Tapping on Tab

To navigate through the views, the user clicks or taps the tabs.

Optional behavior: If the user clicks or taps a tab that’s already open, the container collapses. It opens again when the user clicks any tab.

Use the “expandable” property to specify whether users can collapse the tab container (default = true):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the “expandable” property to false.

The “expandable” property controls the initial state of the container. Do not change the default state (true).

Styles

The two different styles (round tabs and text only) are discussed in the Types section.

In both cases, you can use colors to give users additional orientation.

Information
Do not use colors for decoration only.  Colors should always indicate a status that is relevant to the user.
When using colors, stick to the semantic colors provided by visual design. Do not hard-code color values. Instead, use the CSS extension “Less”.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors.

This example shows a process where one step is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles - Colors
Styles - Colors

Guidelines

Apply the styles as follows:

  • If you have only a few tabs that can easily be visualized with icons, use the icon-only tabs. If a short description is needed, use icons and labels.
  • If the content cannot easily be identified by an icon, use the text-only tabs. They also allow for longer labels.
  • If you are using the icon tab bar in the object view floorplan, use either icon-only or text-only tabs.
    Icons only:
    Use this option if you have only 4–5 tabs that can be very clearly identified by their icon.
    Text only:
    Use this option if you have more than 4–5 tabs, or if there are no clear icons to represent the content. Set the property HeaderMode to Inline.
Do
Counters – Inline Layout ('HeaderMode' set to 'Inline')
Counters – Inline Layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old Layout ('HeaderMode' set to 'Standard')
Counters – Old Layout ('HeaderMode' set to 'Standard')

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B.
    This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Form

Information
With version 1.36, the smart form has been introduced as an additional control for building forms.

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using three different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

The smart form control belongs to the new set of smart controls. Smart controls give developers the possibility to build UIs without the need to build a complex UI code (the term “smart” refers to the annotations that add semantics and structures to the provided data). The goals are to ensure design consistency, keep apps up to date with evolving design guidelines, and reduce the amount of front-end code for building SAP Fiori apps. Compared to the corresponding standard controls, however, the settings may be limited.

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display only
Form control in display only
Mixed form with editable and non-editable fields
Mixed form with editable and non-editable fields
Developer Hint
The smart form property editable really switches the smart form between edit mode and read-only mode. For example, fields become texts and vice versa.

The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.

Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field-ratio 3:5:4
Form with a label-field-ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form, simple form, and smart form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form, simple form, and smart form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms, simple forms, and smart forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – size M (3:5:4)
Form in full screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property and the asterisk will be inserted automatically.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

Placeholder

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

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

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

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

Carousel

The carousel allows the user to browse through a set of items. It always displays one item at a time. From the displayed item, the user can navigate to either the next or the previous item. The interaction resembles browsing through the pages of a book.

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

The control is best known for browsing through a set of images, as it works best when the single items are represented in a way that the user can easily distinguish. Nonetheless, the carousel is not limited to displaying images; it can contain every sap.m control.

Usage

Use the carousel if:

  • You have strong visual representations of the items you want to display.
  • You want to display the items one after the other.

Do not use the carousel if:

  • The items you want to display need to be visible at the same time.
  • The items you want to display are uniform.

Responsiveness

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

When used in non-touch mode, the user can navigate with forward and backward icons displayed on the left and right side of the control.

On touch devices, the carousel control makes use of the swipe gesture to navigate through the items. Therefore, the forward and backward icons are not displayed on touch devices.

The paging indicator (when activated) is visible on each form factor. The paging indicator wraps if not all items fit in one line.

Carousel (size S)
Carousel (size S)

Carousel (size M)
Carousel (size M)

Carousel (size L)
Carousel (size L)

Layout

The carousel control mainly consists of a content area in which the different items are displayed and cycled through.

Optionally, a paging indicator can be displayed floating either above the top or at the bottom of the content area.

On non-touch devices, icons for navigating to the next or previous item are displayed either floating above the left and right side of the content area or in the paging indicator area. This is controlled by the arrowsPlacement property.

Schematic layout of carousel
Schematic layout of carousel

Behavior and Interaction

The current item is displayed in the content area.

Navigating

When the user navigates from a displayed item to another item, the item is moved out of the content area and the next or previous item (depending on the direction of navigation) appears with a sliding transition.

On touch devices, navigation is performed with swipe gestures (swipe right or swipe left).

On non-touch devices, navigation is provided by icons.

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

Navigation – Previous
Navigation – Previous
Navigation – Next (hover)
Navigation – Next (hover)

Looping

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

Paging

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

Paging indicator
Paging indicator

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

Paging indicator
Paging indicator

Resources

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

Elements and Controls

Image (guidelines)

Implementation

Dynamic Side Content

Dynamic side content is a layout control that displays additional content to help the user better understand the data that’s being displayed on the screen.  It is displayed in a way that flexibly adapts to different screen sizes.

App development teams can configure the behavior of the control on smaller screen sizes by following the relevant guidelines.

Dynamic side content layout
Dynamic side content layout

Usage

Use dynamic side content if:

  • You want to display information that:
    • Will enrich the main content and will help the user better perform his/her tasks;
    • Has meaning only when it is displayed next to the given container (side-by-side, below or on top of it);
    • Influences the main content (for example, a filter for list; settings for chart, details for map).
  • Users should have access to all of the key functions and critical information in the app even if they do not see the side content. This is important because on smaller screen sizes it may be difficult to display the side content in a way that is easily accessible for the user.

Do not use dynamic side content if:

  • You want to display critical information that should be visible all the time. The dynamic side content is not meant to split the page into two equally important sections.

  • You want to display navigation or drilldown.

Layout

Dynamic side content is displayed next to (left or right), on top of, or below a container that consists of the main information to which it is directly related.

The dynamic side content can be closed by a button that is displayed in its toolbar.

The dynamic side content can be opened, if it set to hidden, with an action within the container to which it is directly related, or by an action displayed in the container-related toolbar, if it is available.

When the dynamic side content is displayed side-by-side to the container, it doesn’t overlay it. The main container narrows down and makes space for the additional content to be displayed.

  • Dynamic side content positioning
  • Dynamic side content positioning
  • Dynamic side content positioning
  • Dynamic side content positioning

Responsiveness

The dynamic side content control is built for different screen sizes and layouts.

Different sizes of dynamic side content

  • Dynamic side content - Size S
  • Dynamic side content - Size M
  • Dynamic side content - Size L

The default screen layout features the side content on the left or right side of the screen, covering 25% of the screen width on a large desktop (over 1440 px).

Dynamic side content - Default layout
Dynamic side content - Default layout

On smaller screen sizes (under 1440 px), the side content occupies 33% of the screen width to accommodate the nested controls. If the side content width falls below 320 px, the side content automatically slides under the main content, unless the app development team specifies that it should disappear.

Dynamic side content - smaller screen sizes
Dynamic side content - smaller screen sizes

On screen sizes of less than or equal to 720 px, the side content automatically disappears from the screen (unless specified to stay under the content) and can be triggered from a preset trigger (specified within the app). When the side content is triggered, it replaces the main content. We recommend that you always place the trigger for the side content in the same location, such as in the container toolbar.

Equal split: A special view of the side content is the 50:50 view, which enables users to show more data, for example, for comparison purposes. The responsive behavior of the equal split is the same as in the standard view: The side content disappears on screen widths of less than 720 px and can only be viewed by triggering it.

Dynamic side content - Equal split
Dynamic side content - Equal split

The app development team may specify that the side content should slide under the main content when the screen is resized to a smaller width. Sliding the side content under the main content on smaller screens allows it to remain on the screen at all times. However, it may only be accessible via scrolling.

Guidelines

Dynamic Side Content in Object Page

Dynamic side content can be used within the object page. Use dynamic side content within a section if you want to give the user additional data related to this section. If you want to display additional information about the object such as a timeline, include this information as a new section.

Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page
Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page

Do not separate the screen into two panels. Do not use it for navigation, for drilldown, or to show information that related to the entire object.

Dynamic Side Content in Dynamic Page

Do not separate the page into two panels when you are using it inside the dynamic page. The dynamic side content should be placed directly next to the page container and under the header container. The header snaps manually and the both sections have their own scrollbars.

Do
Correct usage of dynamic side content in dynamic page
Correct usage of dynamic side content in dynamic page
Don't
Wrong usage of the dynamic side content in dynamic page
Wrong usage of the dynamic side content in dynamic page

Examples

Dynamic side content in object page, used with map
Dynamic side content in object page, used with map
Dynamic side content in object page, used with planning calendar
Dynamic side content in object page, used with planning calendar
Dynamic side content with event list
Dynamic side content with event list

Use of Controls in the Dynamic Side Content

You can use most of the main controls in the dynamic side content, such as text, simple form, chart, list, panel, tree, timeline, or feed and notes. However, you must make sure that the control doesn’t result in the appearance of a horizontal scrollbar.

Do not use complex controls, such as tables.

Navigation

The side content is always related to the main content, so it must show content that can be triggered from the main content. This also means minimizing navigation, such as drill-ins within the side content, and displaying content that is triggered from the main content area. An example would be showing additional details such as contact information or conversation history. If a different type of data relates to the main content, app developers can implement a switcher in the side content. However, we recommend that you keep the side content free of additional navigation elements.

Triggering the side content

The side content can be set to hidden by default, and it automatically disappears when the screen width is less than or equal to 720 px (except when it is set to be under the main content).The app design team can define the trigger point. Our recommendation is to put a transparent text button with a meaningful label in the container toolbar, or an action inside the container the dynamic side content is related to. Ensure that the user can understand how to trigger the side content. Please, avoid using icons, because they can confuse the user.

Hiding the side content

The side content should be hidden from the header (top) section of the side content. The side content container itself has no header. We therefore strongly recommend that you use a toolbar control with a title, a transparent button labeled Close, and a spacer between them.

Hiding side content – From the header section
Hiding side content – From the header section

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

Map Container

The map container is a predefined feature set for maps. It fits most use cases and makes it easier for app developers to work with maps.

If you wish to display a geomap or an analytic map without using the map container features, the app developer can also opt to use the analytic map or geomap control.

Responsiveness

The width and height of the map container are defined by the surrounding application layout.

The map container uses the overflow toolbar control. This control is based on the sap.m.Toolbar and provides overflow when the contents do not fit in the visible area.

Note: Map container on smartphone displayed menu button instead of list panel icon because of the small screen size.

Components

Overview of map container components
Overview of map container components

The map container includes the following components:

  • A map (geomap or analytic map)
  • Transparent toolbar containing the following buttons:
    • View switch (optional), such as between geomaps and analytic maps
    • Selection menu (optional)
    • Personalization/settings (optional)
    • Full-screen mode
    • Overflow toolbar (generic)
  • A list panel stack, which can be used for a legend or other application-specific content
  • Navigation tools such as:
    • Measure
    • Scale
    • Zoom in/zoom out, including rectangular zoom
    • Home button

View Switch (Optional)

View switches are optional control. This control allows the user to switch between different map types, charts, and table layouts. You should consider using a view switch for accessibility reasons. For example, users with visual impairments might have a hard time working with subtle color differences or specific color gradients, and might prefer switching to a table view instead.

We recommend using no more than three types of alternate visualization. The segmented button control is used to display the types of visualization available in the view switch, and highlights the type of visualization that is being currently displayed.

The button control gives the user the option to switch between the geomap, analytic map and image view.
The button control gives the user the option to switch between the geomap, analytic map and image view.

Menu for Selection Modes (Optional)

The menu for selection modes enables the user to switch between the available selection modes: single, rectangular, and lasso. These buttons are optional.

Selection menu
Selection menu

Personalization (Optional)

A personalization button is provided and can be enabled/disabled by the app developer. The corresponding popover and details need to be implemented by the app developer.

The personalization/settings button can be used to show or hide a legend and labels, for example.

Personalization/settings button
Personalization/settings button

Full-Screen Mode

The map container can be viewed on full-screen mode (property: fullScreen). For desktop and tablet, the Full Screen button is always placed at the top right of the transparent toolbar.

The user can toggle between embedded and full-screen mode via the Maximize Full Screen toggle button. In full-screen mode, the map container occupies the entire width and height. The toolbar replaces the page header bar, and the Minimize icon appears.

For smartphones, the Full Screen button is disabled as the map container is used in full-screen mode by default.

Initiate full-screen button
Initiate full-screen button
Minimize full-screen button
Minimize full-screen button

Overflow (Generic)

The overflow is activated if there is not enough space on the screen for all the chart bar actions. It is generated automatically.

When the user clicks the overflow button, a popover appears. In this action sheet, all icon buttons are labelled with text.

All buttons go into the overflow from right to left.

Overflow button
Overflow button

Prioritization

You can also prioritize the actions in the toolbar by applying one of five different statuses to them:

  • Always overflow: The action will always move into the overflow.
  • Disappear: This applies to actions that are not very relevant for the user, and which can disappear if space is limited.
  • Low: This applies to actions that the user seldom needs; these actions then move first into the overflow.
  • High: These actions remain visible until all actions that are tagged ‘disappear’, ‘low’, or that are untagged, have moved into the overflow.
  • Never overflow: These actions will always visible in the toolbar.

All items have equal priority by default. If two items have the same priority, the one on the right overflows first.

Grouping

Items can overflow together, even if they are in different positions. Elements that belong to a group should not have ‘always overflow’ or ‘never overflow’ statuses as these priorities force the items to remain either in the toolbar or in the overflow area. When group elements have different statuses, the priority of the group is defined by the highest priority of its elements.

List Panel Stack (Optional)

The list panel stack is aligned to the left in the toolbar. It can be used for a legend and other application-specific content. The list panel stack can be collapsed in a way that only the icons of the different list panels will be seen. We recommend using icons that are easy to understand for each panel, as these icons will be the only visible element when the panels are collapsed. The collapsed list panels serve as quick access to the clicked panel icon.

If you are not using icons for the panels, do not allow the panels to collapse.

The default width of the list panel stack is auto. We recommend defining a precise width to avoid having the width permanently change according to the content. The list panel stack will remain visible on the map, whereas the toolbar buttons will be hidden.

As a general rule, avoid using too many panels as too much scrolling will increase the complexity of the application.

The list panel provides the same features as the standard list item:

  • Grouping
  • Select items
  • Include Icons/color markers or pictures
  • Show counter
Collapsed list panel stack (desktop)
Collapsed list panel stack (desktop)
Expanded list panel stack (desktop)
Expanded list panel stack (desktop)

Legend

We recommend to include the map legend in the list panel. All necessary features for a legend are provided through the list panel stack (see above).

If your specific use case does not allow you to include the legend in the list panel, you can also use the map legend.

Navigation Tools

Home Button

The map container provides a Home button. Clicking on the Home button leads to the initial zoom position.

Home button
Home button

Rectangular Zoom

The Rectangular Zoom button can be used to zoom to a specific position. The rectangular zoom is enabled for the compact form factor by default, and disabled for the cozy form factor. For more information on cozy and compact form factors, see content density.

Rectangular Zoom button
Rectangular Zoom button

Zoom In/ Zoom Out

The map container provides Zoom In ( ) and Zoom Out ( ) icon buttons, which are positioned on the bottom right corner of the map. When the user clicks these buttons, the chart automatically zooms in or out to the most appropriate scale.

By default, these buttons are enabled.

Zoom In/Zoom Out button
Zoom In/Zoom Out button

Behavior and Interaction

The buttons have a set priority for the overflow by default. The application developer can change this priority. High-prioritized buttons will overflow last.

On desktop and tablet devices, the list panel stack is always visible, whereas the transparent toolbar overflows. The navigation control is hidden behind the panel list stack.

On a smartphone devices, the list panel stack is minimized to a menu button on the top left. The menu icon always remains on the screen, whereas the transparent toolbar buttons overflow. Clicking on the menu button, the list panel stack opens in full-screen mode.

We generally recommend using either icon buttons or text buttons within the transparent toolbar, but not both. Icons and text should not be combined into one button. Buttons with icon and text only appear in the overflow menu. Buttons are always aligned to the right.

Guidelines

  • Think carefully about what actions you really need in the transparent map toolbar – do not overload the map toolbar with actions.
  • Think carefully about what content you really need in the panel list stack – do not overload the panel with content.
  • Think carefully about which features make sense on the map if the map is not used in full screen. For example, it wouldn’t make sense for a map to have a list panel stack if it is being featured on a card of an overview page.
  • Use tooltips for switchable content. For example, label icon buttons as “geomap” or “analytic map” in the toolbar.

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

Implementation

No links.

Carousel

The carousel allows the user to browse through a set of items. It always displays one item at a time. From the displayed item, the user can navigate to either the next or the previous item. The interaction resembles browsing through the pages of a book.

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

The control is best known for browsing through a set of images, as it works best when the single items are represented in a way that the user can easily distinguish. Nonetheless, the carousel is not limited to displaying images; it can contain every sap.m control.

Usage

Use the carousel if:

  • You have strong visual representations of the items you want to display.
  • You want to display the items one after the other.

Do not use the carousel if:

  • The items you want to display need to be visible at the same time.
  • The items you want to display are uniform.

Responsiveness

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

When used in non-touch mode, the user can navigate with forward and backward icons displayed on the left and right side of the control.

On touch devices, the carousel control makes use of the swipe gesture to navigate through the items. Therefore, the forward and backward icons are not displayed on touch devices.

The paging indicator (when activated) is visible on each form factor. The paging indicator wraps if not all items fit in one line.

Carousel (size S)
Carousel (size S)

Carousel (size M)
Carousel (size M)

Carousel (size L)
Carousel (size L)

Layout

The carousel control mainly consists of a content area in which the different items are displayed and cycled through.

Optionally, a paging indicator can be displayed floating either above the top or at the bottom of the content area.

On non-touch devices, icons for navigating to the next or previous item are displayed either floating above the left and right side of the content area or in the paging indicator area. This is controlled by the arrowsPlacement property.

Schematic layout of carousel
Schematic layout of carousel

Behavior and Interaction

The current item is displayed in the content area.

Navigating

When the user navigates from a displayed item to another item, the item is moved out of the content area and the next or previous item (depending on the direction of navigation) appears with a sliding transition.

On touch devices, navigation is performed with swipe gestures (swipe right or swipe left).

On non-touch devices, navigation is provided by icons.

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

Navigation – Previous
Navigation – Previous
Navigation – Next (hover)
Navigation – Next (hover)

Looping

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

Paging

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

Paging indicator
Paging indicator

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

Paging indicator
Paging indicator

Resources

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

Elements and Controls

Image (guidelines)

Implementation

Form

Information
With version 1.36, the smart form has been introduced as an additional control for building forms.

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using three different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

The smart form control belongs to the new set of smart controls. Smart controls give developers the possibility to build UIs without the need to build a complex UI code (the term “smart” refers to the annotations that add semantics and structures to the provided data). The goals are to ensure design consistency, keep apps up to date with evolving design guidelines, and reduce the amount of front-end code for building SAP Fiori apps. Compared to the corresponding standard controls, however, the settings may be limited.

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form Control in read-only mode
Form Control in read-only mode
Form Control in editable mode
Form Control in editable mode
Developer Hint
The smart form property editable really switches the smart form between edit mode and read-only mode. For example, fields become texts and vice versa.

The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

form with a label-field-ratio 3:5:4
form with a label-field-ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form, simple form, and smart form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form, simple form, and smart form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.
Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms, simple forms, and smart forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – size M (3:5:4)
Form in full screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

Placeholder

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

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

Also do not use the placeholder as a repetition of the label.

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

Form

Information
With SAPUI5 version 1.36, the smart form has been introduced as an additional control for building forms.

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using three different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

The smart form control belongs to the new set of smart controls. Smart controls give developers the possibility to build UIs without the need to build a complex UI code (the term “smart” refers to the annotations that add semantics and structures to the provided data). The goals are to ensure design consistency, keep apps up to date with evolving design guidelines, and reduce the amount of front-end code for building SAP Fiori apps. Compared to the corresponding standard controls, however, the settings may be limited.

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: the data is presented as label-input field pairs to allow users to enter data.
  • Mixed: some fields are editable and some are not.
Form in read-only mode
Form in read-only mode
Form in editable mode
Form in editable mode
Developer Hint
The smart form property “editable” switches the smart form between edit and read-only modes. For example, fields become texts and vice versa.

The form and simple form property “editable” only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the entire form from editable to read-only mode, or vice versa.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general, if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend changing the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

form with a label-field-ratio 3:5:4
form with a label-field-ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected in forms and simple forms, you must change the property adjustLabelSpan from its default true to false.

Otherwise:

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for backward compatibility reasons.

Input controls such as input fields can be displayed in both cozy and compact mode. To horizontally align a label next to a field, the form has different CSS in cozy and compact modes. For more information, see content density.

Size S (Smartphones and Dialogs)

The form, simple form, and smart form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form, simple form, and smart form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.
Form in size M
Form in size M

Size L

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

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

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

Size XL

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

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

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms, simple forms, and smart forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title. Instead, use the form title.

Form with only one group (using form title)
Form with only one group (using form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full-screen – size M (3:5:4)
Form in full-screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

Placeholder

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

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

Also do not use the placeholder as a repetition of the label.

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

Form

Information
With SAPUI5 version 1.36, the smart form has been introduced as an additional control for building forms.

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using three different controls:

The simple form control gives you the same result as the form control, but in a much easier way:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).

The smart form control belongs to the new set of smart controls. Smart controls give developers the possibility to built UIs with annotations and without the need to build a complex UI code. Compared to the corresponding standard controls, however, the settings may be limited.

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: users can enter data.
  • Mixed: some fields are editable and some are not.
Editable form
Editable form
Read-only form
Read-only form
Developer Hint
The smart form property “editable” switches the smart form between edit and read-only modes. For example, fields become texts and vice versa.

The form and simple form property “editable” only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the entire form from editable to read-only mode, or vice versa.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

The default value of breakpointM is 600. This means that as soon as the width of the form reaches 600 px, it changes from M to S. The value of breakpointM is the first value of the smaller size.

If the value of breakpointM is 600, size M is shown when reaching a width of 601 px.

Form, breakpointM, size M
Form, breakpointM, size M

If the value of breakpointM is 600, size S is shown when reaching a width of 600 px.

Due to padding of the container in which the form is placed, this width is usually reached before the page width reaches its breakpoint from M to S. This means that the form changes from M to S before the page does. To set the form’s breakpoint individually and synchronize it with the page, you can use the property breakpointM.

Form, Breakpoint M, S size
Form, Breakpoint M, S size

The properties “breakpointL” between sizes L and M, and “breakpointXL” between sizes XL and L, work in the same way. The default value of breakpointL is 1024, and of breakpointXL it is 1440.

For each size, you can define how many grid columns are used for labels, fields (implicitly), and empty grid columns (emptySpanL, emptySpanM, emptySpanS). The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the entry fields where necessary. This ratio is displayed in this document as x:y:z, where x is the number of grids used by the labels, y represents the fields, and z the empty columns.

To make the properties “labelSpanXL”, “labelSpanL”, “labelSpanM”, and “labelSpanS” work as expected in the responsive grid layout (for example, to ensure that labelSpanL sets the label span in size L) you must change the property “adjustLabelSpan” to “false” in forms and simple forms. The value of the property “adjustLabelSpan” is set to “true” by default for reasons of backward compatibility.

  • “labelSpanL” is used for labels in forms with several form groups arranged into more than one column. It applies for both M and L screen sizes.
  • “labelSpanM” is used for labels in forms arranged into one column. It applies for both M and L screen sizes.
  • “labelSpanS” is used only for screen size S, as expected.

Input controls such as input fields can be displayed in both cozy and compact mode. To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form, simple form, and smart form use a single-column layout in size S by default (not to be confused with the underlying grid columns). The form groups are positioned below each other in a single column. The labels are positioned above the input field or value to avoid truncation.

The label-field ratio is 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form in size S
Form in size S

Size M

The breakpoints for size M are set by default to 600 px (breakpointM = 600) and 1024 px (breakpointL = 1024). This means that if the form has more than 600 px, but no more than 1024 px available, it renders the M layout. The M layout ranges from 601 px to 1024 px. It can be changed with the properties breakpointM and breakpointL, which are properties of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

The M size form has a single-column layout by default in which the labels are positioned in the same row as the corresponding input field or value. The form groups are positioned below each other.

The label-field ratio is 2:10:0 (2 grid columns used by the labels, 10 grid columns used by the fields, and 0 grid columns used by empty columns).

We highly recommend changing this default layout according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form in size M
Form in size M

Size L

The breakpoints for size L are set by default to 1024 px (breakpointL = 1024 ) and 1440 px (breakpointXL = 1440). This means that if the form has more than 1024 px, but no more than 1440px available, it renders the L layout. So the L layout ranges from 1025 px to 1440 px. It can be changed with the properties breakpointL and breakpointXL, which are properties of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

To have all the information on one screen and avoid scrolling, the form groups are placed next to each other in two columns by default. In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

Form in size L
Form in size L

Size XL

The breakpoint for size XL is set by default to 1440 px. This means that if more than 1440 px are available, the form is rendered in XL layout. It can be changed with the property breakpointXL, which is a property of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

To have all the information on one screen and avoid scrolling, the form groups are placed next to each other in two columns by default (the value is set to -1 and inherits the value of size L). In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

Form in size XL
Form in size XL

Layout

One Page, One Form

One form with one or more groups will usually meet your needs. In this case, use group titles, not the form title. If a form contains only one group, do not use a group title.

If the form is one of several elements on the page, such as tables and lists, you may also set a form title.

One form and one group - No form title
One form and one group - No form title
One form and several groups - No form title
One form and several groups - No form title
A form as one of several elements on a page - Form title
A form as one of several elements on a page - Form title

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Split view, simple form, 4:7:1 (M)
Split view, simple form, 4:7:1 (M)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, 3:5:4 (M)
Simple form, 3:5:4 (M)

Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, 4:8:0 (M)
Simple form, 4:8:0 (M)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (M)
Simple form, two columns (M)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to UI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, one column (L)
Simple form, one column (L)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). Size L goes down to 1025 px, so long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Labels are therefore put above fields.

Simple form, two columns (L)
Simple form, two columns (L)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to UI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, one column (XL)
Simple form, one column (XL)

The responsive grid layout has the new property singleContainerFullSize. If you are using a simple form, set this property directly in the simple form control. Setting this property to ‘false’ enables you to insert empty columns in your form. You can then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty.

Simple form, one-plus-one columns (XL)
Simple form, one-plus-one columns (XL)

If the form is put into a full-screen app, you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Simple form, one-plus-two columns (XL)
Simple form, one-plus-two columns (XL)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (XL)
Simple form, two columns (XL)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, three columns with empty column (XL)
Simple form, three columns with empty column (XL)
Simple form, three columns (XL)
Simple form, three columns (XL)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

  • Recommended: XL2-L2-M2-S1, XL2-L2-M1-S1, XL2-L1-M1-S1
  • Also possible: XL3-L1-M1-S1, XL1-L1, M1, S1
  • Not recommended: XL3-L2-M2-S1, XL3-L2-M1-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Try to arrange form groups in size XL and L in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • Give each field a meaningful label. If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property for this in the API. Do not write the asterisk manually in the label text.
  • At the end of the label, the form container automatically inserts a colon “:”, which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, note that labels are not supported for manual bold formatting.)
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Placeholder

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

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

Also do not use the placeholder as a repetition of the label.

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

Form

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

The simple form control gives you the same result as the form control, but in a much easier way:

The layout and structure are defined by the content that is entered.

  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: users can enter data.
  • Mixed: some fields are editable and some are not.
Editable form
Editable form
Read-only form
Read-only form

The form/simple form property “editable” only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). It does not switch the entire form from editable to read-only mode, or vice versa.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

The default value of breakpointM is 600. This means that as soon as the width of the form reaches 600 px, it changes from M to S. The value of breakpointM is the first value of the smaller size.

If the value of breakpointM is 600, size M is shown when reaching a width of 601 px.

Form, breakpointM, size M
Form, breakpointM, size M

If the value of breakpointM is 600, size S is shown when reaching a width of 600 px.

Due to padding of the container in which the form is placed, this width is usually reached before the page width reaches its breakpoint from M to S. This means that the form changes from M to S before the page does. To set the form’s breakpoint individually and synchronize it with the page, you can use the property breakpointM.

Form, breakpointM, size S
Form, breakpointM, size S

The property breakpointL between sizes L and M works in the same way. The default value of breakpointL is 1024.

An XL breakpoint is not yet supported by forms.

For each size, you can define how many grid columns are used for labels, fields (implicitly), and empty grid columns (emptySpanL, emptySpanM, emptySpanS). The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the entry fields where necessary. This ratio is displayed in this document as x:y:z, where x is the number of grids used by the labels, y represents the fields, and z the empty columns.

To define grid columns for labels, use the “layoutData” property for the label.
The properties “labelSpanL”, “labelSpanM”, and “labelSpanS” do not all work as expected, but cannot be changed without breaking downward compatibility.

  • “labelSpanL” is used for labels in forms with several form groups arranged into more than one column. It applies for both M and L screen sizes.
  • “labelSpanM” is used for labels in forms arranged into one column. It applies for both M and L screen sizes.
  • “labelSpanS” is used only for screen size S, as expected.

Input controls such as input fields can be displayed in both cozy and compact mode. To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form uses a single-column layout in size S by default (not to be confused with the underlying grid columns). The form groups are positioned below each other in a single column. The labels are positioned above the input field or value to avoid truncation.

The label-field ratio is 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form in size S
Form in size S

Size M

The breakpoints for size M are set by default to 600 px (breakpointM = 600) and 1024 px (breakpointL = 1024). This means that if the form has more than 600 px, but no more than 1024 px available, it renders the M layout. The M layout ranges from 601 px to 1024 px. It can be changed with the properties breakpointM and breakpointL, which are properties of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

The M size form has a single-column layout by default in which the labels are positioned in the same row as the corresponding input field or value. The form groups are positioned below each other.

The label-field ratio is 2:10:0 (2 grid columns used by the labels, 10 grid columns used by the fields, and 0 grid columns used by empty columns).

We highly recommend changing this default layout according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form in size M
Form in size M

Size L

The breakpoint for size L is set by default to 1024 px. This means that if more than 1024 px are available, the form is rendered in L layout. It can be changed with the property breakpointL, which is a property of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

To have all the information on one screen and avoid scrolling, the form groups are placed next to each other in two columns by default. In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

Form in size L
Form in size L

Layout

One Page, One Form

One form with one or more groups will usually meet your needs. In this case, use group titles, not the form title. If a form contains only one group, do not use a group title.

If the form is one of several elements on the page, such as tables and lists, you may also set a form title.

One form and one group - No form title
One form and one group - No form title
One form and several groups - No form title
One form and several groups - No form title
A form as one of several elements on a page - Form title
A form as one of several elements on a page - Form title

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Split view, simple form, 4:7:1 (M)
Split view, simple form, 4:7:1 (M)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, 3:5:4 (M)
Simple form, 3:5:4 (M)

Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, 4:8:0 (M)
Simple form, 4:8:0 (M)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with the label-field ratio 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (M)
Simple form, two columns (M)
Developer Hint
Unlike all other L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Wide Screens) – Full Screen

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, one column (L)
Simple form, one column (L)

If the form contains multiple form groups, use a two-column layout with a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (L)
Simple form, two columns (L)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Due to the early breakpoint from M to L (1024 px) and no break point to XL for bigger sizes, L-sized screens must fit large screens as well as screens that are slightly bigger than 1024 px. So if you use a three-column layout for extra wide screens, all labels and fields must also fit on a screen that is slightly bigger than 1024 px. Truncating labels in particular may cause problems here, so they are placed above the fields.

Simple form, three columns (L)
Simple form, three columns (L)

If you use a three-column layout for size L screens, do not use a two-column layout for size M screens as it could create a lot of white space. In this case, use a single-column layout instead.

  • Recommended: L2-M2-S1, L2-M1-S1, L3,M1,S1
  • Also possible: L1, M1, S1
  • Not recommended: L3-M2-S1

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Try to arrange form groups in size L in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • Give each field a meaningful label. If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property for this in the API. Do not write the asterisk manually in the label text.
  • At the end of the label, the form container automatically inserts a colon “:”, which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, note that labels are not supported for manual bold formatting.)
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Placeholder

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

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

Also do not use the placeholder as a repetition of the label.

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

Form

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

The simple form control gives you the same result as the form control, but in a much easier way:

The layout and structure are defined by the content that is entered.

  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: users can enter data.
  • Mixed: some fields are editable and some are not.
Editable form
Editable form
Read-only form
Read-only form

The form/simple form property “editable” only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). It does not switch the entire form from editable to read-only mode, or vice versa.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

The default value of breakpointM is 600. This means that as soon as the width of the form reaches 600 px, it changes from M to S. The value of breakpointM is the first value of the smaller size.

If the value of breakpointM is 600, size M is shown when reaching a width of 601 px.

Form, breakpointM, size M
Form, breakpointM, size M

If the value of breakpointM is 600, size S is shown when reaching a width of 600 px.

Due to padding of the container in which the form is placed, this width is usually reached before the page width reaches its breakpoint from M to S. This means that the form changes from M to S before the page does. To set the form’s breakpoint individually and synchronize it with the page, you can use the property breakpointM.

Form, breakpointM, size S
Form, breakpointM, size S

The property breakpointL between sizes L and M works in the same way. The default value of breakpointL is 1024.

An XL breakpoint is not yet supported by forms.

For each size, you can define how many grid columns are used for labels, fields (implicitly), and empty grid columns (emptySpanL, emptySpanM, emptySpanS). The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the entry fields where necessary. This ratio is displayed in this document as x:y:z, where x is the number of grids used by the labels, y represents the fields, and z the empty columns.

To define grid columns for labels, use the “layoutData” property for the label.
The properties “labelSpanL”, “labelSpanM”, and “labelSpanS” do not all work as expected, but cannot be changed without breaking downward compatibility.

  • “labelSpanL” is used for labels in forms with several form groups arranged into more than one column. It applies for both M and L screen sizes.
  • “labelSpanM” is used for labels in forms arranged into one column. It applies for both M and L screen sizes.
  • “labelSpanS” is used only for screen size S, as expected.

Input controls such as input fields can be displayed in both cozy and compact mode. To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form uses a single-column layout in size S by default (not to be confused with the underlying grid columns). The form groups are positioned below each other in a single column. The labels are positioned above the input field or value to avoid truncation.

The label-field ratio is 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form in size S
Form in size S

Size M

The breakpoints for size M are set by default to 600 px (breakpointM = 600) and 1024 px (breakpointL = 1024). This means that if the form has more than 600 px, but no more than 1024 px available, it renders the M layout. The M layout ranges from 601 px to 1024 px. It can be changed with the properties breakpointM and breakpointL, which are properties of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

The M size form has a single-column layout by default in which the labels are positioned in the same row as the corresponding input field or value. The form groups are positioned below each other.

The label-field ratio is 2:10:0 (2 grid columns used by the labels, 10 grid columns used by the fields, and 0 grid columns used by empty columns).

We highly recommend changing this default layout according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form in size M
Form in size M

Size L

The breakpoint for size L is set by default to 1024 px. This means that if more than 1024 px are available, the form is rendered in L layout. It can be changed with the property breakpointL, which is a property of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

To have all the information on one screen and avoid scrolling, the form groups are placed next to each other in two columns by default. In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

Form in size L
Form in size L

Layout

One Page, One Form

One form with one or more groups will usually meet your needs. In this case, use group titles, not the form title. If a form contains only one group, do not use a group title.

If the form is one of several elements on the page, such as tables and lists, you may also set a form title.

One form and one group - No form title
One form and one group - No form title
One form and several groups - No form title
One form and several groups - No form title
A form as one of several elements on a page - Form title
A form as one of several elements on a page - Form title

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Split view, simple form, 4:7:1 (M)
Split view, simple form, 4:7:1 (M)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, 3:5:4 (M)
Simple form, 3:5:4 (M)

Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, 4:8:0 (M)
Simple form, 4:8:0 (M)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with the label-field ratio 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (M)
Simple form, two columns (M)

Size L (Wide Screens) – Full Screen

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, one column (L)
Simple form, one column (L)

If the form contains multiple form groups, use a two-column layout with a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (L)
Simple form, two columns (L)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Due to the early breakpoint from M to L (1024 px) and no breakpoint to XL for bigger sizes, L-sized screens must fit large screens as well as screens that are slightly bigger than 1024 px. So if you use a three-column layout for extra wide screens, all labels and fields must also fit on a screen that is slightly bigger than 1024 px. Truncating labels in particular may cause problems here, so they are placed above the fields.

Simple form, three columns (L)
Simple form, three columns (L)

If you use a three-column layout for size L screens, do not use a two-column layout for size M screens as it could create a lot of white space. In this case, use a single-column layout instead.

  • Recommended: L2-M2-S1, L2-M1-S1, L3,M1,S1
  • Also possible: L1, M1, S1
  • Not recommended: L3-M2-S1

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Try to arrange form groups in size L in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • Give each field a meaningful label. If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property for this in the API. Do not write the asterisk manually in the label text.
  • At the end of the label, the form container automatically inserts a colon “:”, which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, note that labels are not supported for manual bold formatting.)
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Placeholder

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

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

Also do not use the placeholder as a repetition of the label.

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

Form

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

The simple form control gives you the same result as the form control, but in a much easier way:

The layout and structure are defined by the content that is entered.

  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: users can enter data.
  • Mixed: some fields are editable and some are not.
Editable form
Editable form
Read-only form
Read-only form

The form/simple form property “editable” only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). It does not switch the entire form from editable to read-only mode, or vice versa.

Responsiveness

There is a specific set of form layout controls for forms and simple forms. You must assign one of these form layout controls to each form and simple form by using the property “layout”.

The form layout control defines how labels and fields are arranged on the screen. Always use the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout). Please do not use any other form layout control, as these are only available to enable downward compatibility. 

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

The default value of breakpointM is 600. This means that as soon as the width of the form reaches 600 px, it changes from M to S. The value of breakpointM is the first value of the smaller size.

If the value of breakpointM is 600, on a width of 601 px size M is shown.

Form with breakpointM – Size S
Form with breakpointM – Size S

If the value of breakpointM is 600, size S is shown when reaching a width of 600 px .

Due to padding of the container in which the form is placed, this width is usually reached before the page width reaches its breakpoint from M to S. This means that the form changes from M to S before the page does. To set the form’s breakpoint individually and synchronize it with the page, you can use the property breakpointM.

Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way. The default value of breakpointL is 1024.

For each size, you can define how many grid columns are used for labels, fields (implicitly), and empty grid columns (emptySpanL, emptySpanM, emptySpanS). The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the entry fields where necessary. This ratio is displayed in this document as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

To define grid columns for labels, use the layoutData property for the label.
Exception for labelSpan:

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column. It applies for both M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column. It applies for both M and L screen sizes.
  • labelSpanS is used only for screen size S, as expected.

Input controls such as input fields can be displayed in both cozy and compact mode. To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form uses a single-column layout in size S by default (not to be confused with the underlying grid columns). The form groups are positioned below each other in a single column. The labels are positioned above the input field or value to avoid truncation.

The label-field ratio is 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form in size S
Form in size S

Size M

The breakpoints for size M are set by default to 600 px (breakpointM = 600) and 1024 px (breakpointL = 1024). This means that if the form has more than 600 px, but no more than 1024 px available, it renders the M layout. The M layout ranges from 601 px to 1024 px. It can be changed with the properties breakpointM and breakpointL, which are properties of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

The M size form has a single-column layout by default in which the labels are positioned in the same row as the corresponding input field or value. The form groups are positioned below each other.

The label-field ratio is 2:10:0 (2 grid columns used by the labels, 10 grid columns used by the fields, and 0 grid columns used by empty columns).

We highly recommend changing this default layout according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form in size M
Form in size M

Size L

The breakpoint for size L is set by default to 1024 px. This means that if more than 1024 px are available, the form is rendered in L layout. It can be changed with the property breakpointL, which is a property of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

To have all the information on one screen and avoid scrolling, the form groups are placed next to each other in two columns by default. In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

Form in size L
Form in size L

Layout

One Page, One Form

One form with one or more groups will usually meet your needs. In this case, use group titles, not the form title. If a form contains only one group, do not use a group title.

If the form is one of several elements on the page, such as tables and lists, you may also set a form title.

One form and one group - No form title
One form and one group - No form title
One form and several groups - No form title
One form and several groups - No form title
A form as one of several elements on a page - Form title
A form as one of several elements on a page - Form title

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Split view, simple form, 4:7:1 (M)
Split view, simple form, 4:7:1 (M)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, 3:5:4 (M)
Simple form, 3:5:4 (M)

Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, 4:8:0 (M)
Simple form, 4:8:0 (M)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with the label-field ratio 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (M)
Simple form, two columns (M)

Size L (Wide Screens) – Full Screen

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, one column (L)
Simple form, one column (L)

If the form contains multiple form groups, use a two-column layout with a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (L)
Simple form, two columns (L)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Due to the early breakpoint from M to L (1024 px) and no breakpoint to XL for bigger sizes, L-sized screens must fit large screens as well as screens that are slightly bigger than 1024 px. So if you use a three-column layout for extra wide screens, all labels and fields must also fit on a screen that is slightly bigger than 1024 px. Truncating labels in particular may cause problems here, so they are placed above the fields.

Simple form, three columns (L)
Simple form, three columns (L)

If you use a three-column layout for size L screens, do not use a two-column layout for size M screens as it could create a lot of white space. In this case, use a single-column layout instead.

  • Recommended: L2-M2-S1, L2-M1-S1, L3,M1,S1
  • Also possible: L1, M1, S1
  • Not recommended: L3-M2-S1

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Try to arrange form groups in size L in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • Give each field a meaningful label. If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property for this in the API. Do not write the asterisk manually in the label text.
  • At the end of the label, the form container automatically inserts a colon “:”, which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, note that labels are not supported for manual bold formatting.)
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Placeholder

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

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

Also do not use the placeholder as a repetition of the label.

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

Form

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

The simple form control gives you the same result as the form control, but in a much easier way:

The layout and structure are defined by the content that is entered.

  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: users can enter data.
  • Mixed: some fields are editable and some are not.
Editable form
Editable form
Read-only form
Read-only form

The form/simple form property “editable” only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). It does not switch the entire form from editable to read-only mode, or vice versa.

Responsiveness

There is a specific set of form layout controls for forms and simple forms. You must assign one of these form layout controls to each form and simple form by using the property “layout”.

The form layout control defines how labels and fields are arranged on the screen. Always use the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout). Please do not use any other form layout control, as these are only available to enable downward compatibility. 

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

The default value of breakpointM is 600. This means that as soon as the width of the form reaches 600 px, it changes from M to S. The value of breakpointM is the first value of the smaller size.

If the value of breakpointM is 600, on a width of 601 px size M is shown.

Form with breakpointM – Size S
Form with breakpointM – Size S

If the value of breakpointM is 600, size S is shown when reaching a width of 600 px .

Due to padding of the container in which the form is placed, this width is usually reached before the page width reaches its breakpoint from M to S. This means that the form changes from M to S before the page does. To set the form’s breakpoint individually and synchronize it with the page, you can use the property breakpointM.

Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way. The default value of breakpointL is 1024.

For each size, you can define how many grid columns are used for labels, fields (implicitly), and empty grid columns (emptySpanL, emptySpanM, emptySpanS). The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the entry fields where necessary. This ratio is displayed in this document as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

To define grid columns for labels, use the layoutData property for the label.
Exception for labelSpan:

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column. It applies for both M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column. It applies for both M and L screen sizes.
  • labelSpanS is used only for screen size S, as expected.

Input controls such as input fields can be displayed in both cozy and compact mode. To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form uses a single-column layout in size S by default (not to be confused with the underlying grid columns). The form groups are positioned below each other in a single column. The labels are positioned above the input field or value to avoid truncation.

The label-field ratio is 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form in size S
Form in size S

Size M

The breakpoints for size M are set by default to 600 px (breakpointM = 600) and 1024 px (breakpointL = 1024). This means that if the form has more than 600 px, but no more than 1024 px available, it renders the M layout. The M layout ranges from 601 px to 1024 px. It can be changed with the properties breakpointM and breakpointL, which are properties of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

The M size form has a single-column layout by default in which the labels are positioned in the same row as the corresponding input field or value. The form groups are positioned below each other.

The label-field ratio is 2:10:0 (2 grid columns used by the labels, 10 grid columns used by the fields, and 0 grid columns used by empty columns).

We highly recommend changing this default layout according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form in size M
Form in size M

Size L

The breakpoint for size L is set by default to 1024 px. This means that if more than 1024 px are available, the form is rendered in L layout. It can be changed with the property breakpointL, which is a property of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

To have all the information on one screen and avoid scrolling, the form groups are placed next to each other in two columns by default. In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

Form in size L
Form in size L

Layout

One Page, One Form

One form with one or more groups will usually meet your needs. In this case, use group titles, not the form title. If a form contains only one group, do not use a group title.

If the form is one of several elements on the page, such as tables and lists, you may also set a form title.

One form and one group - No form title
One form and one group - No form title
One form and several groups - No form title
One form and several groups - No form title
One form and several groups - Form title and table
One form and several groups - Form title and table

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Split view, simple form, 4:7:1 (M)
Split view, simple form, 4:7:1 (M)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, 3:5:4 (M)
Simple form, 3:5:4 (M)

Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, 4:8:0 (M)
Simple form, 4:8:0 (M)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with the label-field ratio 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (M)
Simple form, two columns (M)

Size L (Wide Screens) – Full Screen

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, one column (L)
Simple form, one column (L)

If the form contains multiple form groups, use a two-column layout with a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (L)
Simple form, two columns (L)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Due to the early breakpoint from M to L (1024 px) and no breakpoint to XL for bigger sizes, L-sized screens must fit large screens as well as screens that are slightly bigger than 1024 px. So if you use a three-column layout for extra wide screens, all labels and fields must also fit on a screen that is slightly bigger than 1024 px. Truncating labels in particular may cause problems here, so they are placed above the fields.

Simple form, three columns (L)
Simple form, three columns (L)

If you use a three-column layout for size L screens, do not use a two-column layout for size M screens as it could create a lot of white space. In this case, use a single-column layout instead.

  • Recommended: L2-M2-S1, L2-M1-S1, L3,M1,S1
  • Also possible: L1, M1, S1
  • Not recommended: L3-M2-S1

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Try to arrange form groups in size L in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • Give each field a meaningful label. If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property for this in the API. Do not write the asterisk manually in the label text.
  • At the end of the label, the form container automatically inserts a colon “:”, which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, note that labels are not supported for manual bold formatting.)
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Placeholder

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

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

Also do not use the placeholder as a repetition of the label.

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

Carousel

The carousel is a control for browsing through a set of items. It always displays one item at a time. From the displayed item, the user can navigate to either the next or the previous item. The interaction resembles browsing through the pages of a book.

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

The control is best known for browsing through a set of images, as it works best when the single items are represented in a way that the user can easily distinguish. Nonetheless, the carousel is not limited to displaying images; it can contain every sap.m control.

Usage

Use the carousel if:

  • You have strong visual representations of the items you want to display.
  • You want to display the items one after the other.

Do not use the carousel if:

  • The items you want to display need to be visible at the same time.
  • The items you want to display are uniform.

Responsiveness

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

When used in non-touch mode, the user can navigate with forward and backward icons displayed on the left and right side of the control.

On touch devices, the carousel control makes use of the swipe gesture to navigate through the items. Therefore, the forward and backward icons are not displayed on touch devices.

The paging indicator (when activated) is visible on each form factor. The paging indicator wraps if not all items fit in one line.

Carousel (size S)
Carousel (size S)

Carousel (size M)
Carousel (size M)

Carousel (size L)
Carousel (size L)

Layout

The carousel control mainly consists of a content area in which the different items are displayed and cycled through.

Optionally, a paging indicator can be displayed floating either above the top or at the bottom of the content area.

On non-touch devices, icons for navigating to the next or previous item are displayed floating above the left and right side of the content area.

Schematic layout of carousel
Schematic layout of carousel

Behavior and Interaction

The current item is displayed in the content area.

Navigating

When the user navigates from a displayed item to another item, the item is moved out of the content area and the next or previous item (depending on the direction of navigation) appears with a sliding transition.

On touch devices, navigation is performed with swipe gestures (swipe right or swipe left).

On non-touch devices, navigation is provided by icons.

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

Navigation – Previous
Navigation – Previous
Navigation – Next (hover)
Navigation – Next (hover)

Looping

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

Paging

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

Paging indicator
Paging indicator

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

Carousel

The carousel is a control for browsing through a set of items. It always displays one item at a time. From the displayed item, the user can navigate to either the next or the previous item. The interaction resembles browsing through the pages of a book.

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

The control is best known for browsing through a set of images, as it works best when the single items are represented in a way that the user can easily distinguish. Nonetheless, the carousel is not limited to displaying images; it can contain every sap.m control.

Usage

Use the carousel if:

  • You have strong visual representations of the items you want to display.
  • You want to display the items one after the other.

Do not use the carousel if:

  • The items you want to display need to be visible at the same time.
  • The items you want to display are uniform.

Responsiveness

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

When used in non-touch mode, the user can navigate with forward and backward icons displayed on the left and right side of the control.

On touch devices, the carousel control makes use of the swipe gesture to navigate through the items. Therefore, the forward and backward icons are not displayed on touch devices.

The paging indicator (when activated) is visible on each form factor. The paging indicator wraps if not all items fit in one line.

Carousel (size S)
Carousel (size S)

Carousel (size M)
Carousel (size M)

Carousel (size L)
Carousel (size L)

Layout

The carousel control mainly consists of a content area in which the different items are displayed and cycled through.

Optionally, a paging indicator can be displayed floating either above the top or at the bottom of the content area.

On non-touch devices, icons for navigating to the next or previous item are displayed floating above the left and right side of the content area.

Schematic layout of carousel
Schematic layout of carousel

Behavior and Interaction

The current item is displayed in the content area.

Navigating

When the user navigates from a displayed item to another item, the item is moved out of the content area and the next or previous item (depending on the direction of navigation) appears with a sliding transition.

On touch devices, navigation is performed with swipe gestures (swipe right or swipe left).

On non-touch devices, navigation is provided by icons.

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

Navigation to previous item
Navigation to previous item
Forward navigation
Forward navigation

Looping

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

Paging

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

Paging indicator
Paging indicator

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

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking or tapping the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show many facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • An object type has only one tab in the entire app.
    In this case, we recommend removing the icon tab bar and placing the content on the same level as the object header. To replace the tab label, add a headline with the same text (for example, Information).

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Responsiveness - Icon tabs
Responsiveness - Icon tabs
Responsiveness - Text tabs
Responsiveness - Text tabs

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters above the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels do not become too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure that the property UpperCase is disabled and that you enter the labels in title case (Example: Approval Flow).

Types ─ Text-only without counters
Types ─ Text-only without counters
Types ─ Text-only with inline counters
Types ─ Text-only with inline counters

Counters and Text Tabs

If counters are used, set the property HeaderMode to Inline so the counters appear in brackets after the labels.

Please do not use the old layout that shows the counters on top of the labels (Headermode = Standard).

Do
Counters – Inline Layout ('HeaderMode' set to 'Inline')
Counters – Inline Layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old Layout ('HeaderMode' set to 'Standard')
Counters – Old Layout ('HeaderMode' set to 'Standard')

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Please note that starting with SAPUI5 version 1.40, you should only use the horizontal type of label (icon and label side by side).

If your labels get truncated, consider using shorter labels or text tabs (without icons), as text tabs cannot get truncated.

Types - Icons with counters
Types - Icons with counters
Types - Icons with counters and labels
Types - Icons with counters and labels
Types - Icon-only
Types - Icon-only

Tabs as Filters

If you build the tab bar as a filter, it can comprise two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 189 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Types - Filter
Types - Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Types - Process
Types - Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Behavior and Interaction

Clicking/Tapping on Tab

To navigate through the views, the user clicks or taps the tabs.

Optional behavior: If the user clicks or taps a tab that’s already open, the container collapses. It opens again when the user clicks any tab.

Use the “expandable” property to specify whether users can collapse the tab container (default = true):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the “expandable” property to false.

The “expandable” property controls the initial state of the container. Do not change the default state (true).

Styles

The two different styles (round tabs and text only) are discussed in the Types section.

In both cases, you can use colors to give users additional orientation.

Information
Do not use colors for decoration only.  Colors should always indicate a status that is relevant to the user.
When using colors, stick to the semantic colors provided by visual design. Do not hard-code color values. Instead, use the CSS extension “Less”.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors.

This example shows a process where one step is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles - Colors
Styles - Colors

Guidelines

Apply the styles as follows:

  • If you have only a few tabs that can easily be visualized with icons, use the icon-only tabs. If a short description is needed, use icons and labels.
  • If the content cannot easily be identified by an icon, use the text-only tabs. They also allow for longer labels.
  • If you are using the icon tab bar in the object view floorplan, use either icon-only or text-only tabs.
    Icons only:
    Use this option if you have only 4–5 tabs that can be very clearly identified by their icon.
    Text only:
    Use this option if you have more than 4–5 tabs, or if there are no clear icons to represent the content. Set the property HeaderMode to Inline.
Do
Counters – Inline Layout ('HeaderMode' set to 'Inline')
Counters – Inline Layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old Layout ('HeaderMode' set to 'Standard')
Counters – Old Layout ('HeaderMode' set to 'Standard')

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B.
    This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking or tapping the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show many facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • An object type has only one tab in the entire app.
    In this case, we recommend removing the icon tab bar and placing the content on the same level as the object header. To replace the tab label, add a headline with the same text (for example, Information).

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Icon tab bar - Size S
Icon tab bar - Size S
Icon tab bar - Size M
Icon tab bar - Size M
Icon tab bar - Size L/XL
Icon tab bar - Size L/XL

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters above the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels are not too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure to put the titles in UPPERCASE LETTERS.

Icon tab bar – Types – Text and counters
Icon tab bar – Types – Text and counters
Icon tab bar – Types – Text only
Icon tab bar – Types – Text only

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Please note that labels under the tabs do not wrap. Texts that exceed the width of the tab are truncated.

If you need longer labels, put the labels next to the tabs. If they are still truncated, use shorter labels or text-only tabs.

Icon tab bar – Types – Icons and labels (vertical)
Icon tab bar – Types – Icons and labels (vertical)
Icon tab bar – Types – Icons and labels (horizontal)
Icon tab bar – Types – Icons and labels (horizontal)
Icon tab bar – Types – Icons only
Icon tab bar – Types – Icons only

Tabs as Filters

If you build the tab bar as a filter, it can contain two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 14 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Icon tab bar – Types – Filter
Icon tab bar – Types – Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Icon tab bar – Types – Process
Icon tab bar – Types – Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Behavior and Interaction

Clicking/Tapping on Tab

To navigate through the views, the user clicks or taps the tabs.

Optional behavior: If the user clicks or taps a tab that’s already open, the container collapses. It opens again when the user clicks any tab.

Use the “expandable” property to specify whether users can collapse the tab container (default = true):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the “expandable” property to false.

The “expandable” property controls the initial state of the container. Do not change the default state (true).

Styles

The two different styles (round tabs and text only) are discussed in the Types section.

In both cases, you can use colors to give users additional orientation.

Information
Do not use colors for decoration only.  Colors should always indicate a status that is relevant to the user.
When using colors, stick to the semantic colors provided by visual design. Do not hard-code color values. Instead, use the CSS extension “Less”.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors.

This example shows a process where one step is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles – Colors
Styles – Colors

Guidelines

Apply the styles as follows:

  • If you have only a few tabs that can easily be visualized with icons, use the icon-only tabs. If a short description is needed, use icons and labels.
  • If the content cannot easily be identified by an icon, use the text-only tabs. They also allow for longer labels.
  • If you are using the icon tab bar in the object view floorplan, use either icon-only or text-only tabs.
    Icons only:
    Use this option if you have only 4–5 tabs that can be very clearly identified by their icon.
    Text only:
    Use this option if you have more than 4–5 tabs, or if there are no clear icons to represent the content.

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B.
    This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking or tapping the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show many facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • An object type has only one tab in the entire app.
    In this case, we recommend removing the icon tab bar and placing the content on the same level as the object header. To replace the tab label, add a headline with the same text (for example, Information).

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Icon tab bar - Size S
Icon tab bar - Size S
Icon tab bar - Size M
Icon tab bar - Size M
Icon tab bar - Size L/XL
Icon tab bar - Size L/XL

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters above the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels are not too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure to put the titles in UPPERCASE LETTERS.

Icon tab bar – Types – Text and counters
Icon tab bar – Types – Text and counters
Icon tab bar – Types – Text only
Icon tab bar – Types – Text only

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Please note that labels under the tabs do not wrap. Texts that exceed the width of the tab are truncated.

If you need longer labels, put the labels next to the tabs. If they are still truncated, use shorter labels or text-only tabs.

Icon tab bar – Types – Icons and labels (vertical)
Icon tab bar – Types – Icons and labels (vertical)
Icon tab bar – Types – Icons and labels (horizontal)
Icon tab bar – Types – Icons and labels (horizontal)
Icon tab bar – Types – Icons only
Icon tab bar – Types – Icons only

Tabs as Filters

If you build the tab bar as a filter, it can contain two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 14 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Icon tab bar – Types – Filter
Icon tab bar – Types – Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Icon tab bar – Types – Process
Icon tab bar – Types – Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Behavior and Interaction

Clicking/Tapping on Tab

To navigate through the views, the user clicks or taps the tabs.

Optional behavior: If the user clicks or taps a tab that’s already open, the container collapses. It opens again when the user clicks any tab.

Use the “expandable” property to specify whether users can collapse the tab container (default = true):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the “expandable” property to false.

The “expandable” property controls the initial state of the container. Do not change the default state (true).

Styles

The two different styles (round tabs and text only) are discussed in the Types section.

In both cases, you can use colors to give users additional orientation.

Information
Do not use colors for decoration only.  Colors should always indicate a status that is relevant to the user.
When using colors, stick to the semantic colors provided by visual design. Do not hard-code color values. Instead, use the CSS extension “Less”.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors.

This example shows a process where one step is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles – Colors
Styles – Colors

Guidelines

Apply the styles as follows:

  • If you have only a few tabs that can easily be visualized with icons, use the icon-only tabs. If a short description is needed, use icons and labels.
  • If the content cannot easily be identified by an icon, use the text-only tabs. They also allow for longer labels.
  • If you are using the icon tab bar in the object view floorplan, use either icon-only or text-only tabs.
    Icons only:
    Use this option if you have only 4–5 tabs that can be very clearly identified by their icon.
    Text only:
    Use this option if you have more than 4–5 tabs, or if there are no clear icons to represent the content.

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B.
    This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking or tapping the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show many facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • An object type has only one tab in the entire app.
    In this case, we recommend removing the icon tab bar and placing the content on the same level as the object header. To replace the tab label, add a headline with the same text (for example, Information).

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Icon tab bar - Size S
Icon tab bar - Size S
Icon tab bar - Size M
Icon tab bar - Size M
Icon tab bar - Size L/XL
Icon tab bar - Size L/XL

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can show counters above the text to indicate the number of items on the tab page.

If you use text-only tabs, make sure to put the titles in UPPER CASE LETTERS.

Icon tab bar - Types - Text and counters
Icon tab bar - Types - Text and counters
Icon tab bar - Types - Text only
Icon tab bar - Types - Text only

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Please note that labels under the tabs do not wrap. Texts that exceed the width of the tab are truncated.

If you need longer labels, put the labels next to the tabs. If they are still truncated, use shorter labels or text-only tabs.

Icon tab bar – Types – Icons and labels (vertical)
Icon tab bar – Types – Icons and labels (vertical)
Icon tab bar – Types – Icons and labels (horizontal)
Icon tab bar – Types – Icons and labels (horizontal)
Icon tab bar – Types – Icons only
Icon tab bar – Types – Icons only

Tabs as Filters

If you build the tab bar as a filter, it can contain two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 14 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Icon tab bar – Types – Filter
Icon tab bar – Types – Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Icon tab bar – Types – Process
Icon tab bar – Types – Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Behavior and Interaction

Clicking/Tapping on Tab

To navigate through the views, the user clicks or taps the tabs.

Optional behavior: If the user clicks or taps a tab that’s already open, the container collapses. It opens again when the user clicks any tab.

Use the “expandable” property to specify whether users can collapse the tab container (default = true):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the “expandable” property to false.

The “expandable” property controls the initial state of the container. Do not change the default state (true).

Styles

The two different styles (round tabs and text only) are discussed in the Types section.

In both cases, you can use colors to give users additional orientation.

Information
Do not use colors for decoration only.  Colors should always indicate a status that is relevant to the user.
When using colors, stick to the semantic colors provided by visual design. Do not hard-code color values. Instead, use the CSS extension “Less”.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors.

This example shows a process where one step is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles – Colors
Styles – Colors

Guidelines

Apply the styles as follows:

  • If you have only a few tabs that can easily be visualized with icons, use the icon-only tabs. If a short description is needed, use icons and labels.
  • If the content cannot easily be identified by an icon, use the text-only tabs. They also allow for longer labels.
  • If you are using the icon tab bar in the object view floorplan, use either icon-only or text-only tabs.
    Icons only:
    Use this option if you have only 4–5 tabs that can be very clearly identified by their icon.
    Text only:
    Use this option if you have more than 4–5 tabs, or if there are no clear icons to represent the content.

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B.
    This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Panel

The panel is a container for grouping and displaying information. It can be collapsed to save space on the screen.

Usage

Use the panel if:

  • You need to group or display information.
  • You want to give users the option of hiding this information.
  • You want to show additional information on demand (for example, a panel could show optional input fields for an advanced search).

Example

  • Panel - Value Help Dialog Closed
  • Panel - Value Help Dialog Open

Responsiveness

If the width of the panel is set to 100% (default), the panel and its children are resized responsively, depending on its parent container.

Layout

  • The panel control is a container for controls.
  • The panel can have a solid or semi-transparent background.
  • The panel always includes a header.
  • An info bar can be added to the panel to show extra information.

Examples

Panel with a title toolbar
Panel with a title toolbar
Panel with a title toolbar and info bar
Panel with a title toolbar and info bar

Types

There are two types of panels: fixed and expandable.

Fixed Panel

Fixed panels are useful for grouping custom content. They include headers and info toolbars.

Fixed panel
Fixed panel

Expandable Panel

Expandable panels are much like fixed panels, except their content can be expanded and collapsed (including the info toolbar, if available).

  • Panel Expandable1
  • Panel Expandable2

Components

A panel consists of a title bar with a header text or header toolbar, an info toolbar (optional), and a content area.

The title inside the title bar can be added by using the “headerText” property. If you use the “headerToolbar” aggregation, the “headerText” property is ignored. With the “headerToolbar” aggregation, you can add a toolbar with any toolbar content inside the title bar. For example, if you need a title text on the left and some action buttons on the right, add a title to the toolbar’s content aggregation, toolbar spacer, and then your buttons.

Header toolbar of a panel
Header toolbar of a panel

Behavior and Interaction

Expand/Collapse

  • When the panel is expandable, an arrow icon (pointing to the right) appears in front of the header. Click or tap this icon to expand the panel.
  • When the animation is activated, expand/collapse uses a smooth animation to open or close the content area.
  • When the panel expands, the arrow icon rotates 90 degrees clockwise.
  • When the panel collapses, the arrow icon rotates 90 degrees counterclockwise.
  • The buttons in the header can be clicked/tapped separately.

Example

  • Panel ExpandCollapse1
  • Panel ExpandCollapse2

Overflow Scrolling (Content Area)

  • By setting the height to use the default property “auto”, the height of the content area will automatically be adjusted to match the height of its content.
  • When the height of the panel is set to a fixed size, the content area can be scrolled through.

Panel With Scrolling

Panel with a fixed height (scrolling activated)
Panel with a fixed height (scrolling activated)

Panel Without Scrolling

Panel with auto height (no scrolling)
Panel with auto height (no scrolling)

Guidelines

  • Nesting two or more panels is not recommended.
  • Do not stack too many panels on one page.

Exceptions

If you add a header toolbar (sap.m.Toolbar) via aggregations, it will overwrite the “headerText” property.

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

  • No links

Panel

The panel is a container for grouping and displaying information. It can be collapsed to save space on the screen.

Usage

  • Use the panel if:

    • You need to group or display information.
    • You want to give users the option of hiding this information.
    • You want to show additional information on demand (for example, a panel could show optional input fields for an advanced search).

Example

  • Panel - Value Search Dialog Closed
  • Panel - Value Search Dialog Open

Responsiveness

If the width of the panel is set to 100% (default), the panel and its children are resized responsively, depending on its parent container.

Layout

  • The panel control is a container for controls.
  • The panel can have a solid or semi-transparent background.
  • The panel always includes a header.
  • An info toolbar can be added to the panel to show extra information.

Examples

Panel with a title toolbar
Panel with a title toolbar
Panel with a title toolbar and infobar
Panel with a title toolbar and infobar

Types

There are two types of panels: fixed and expandable.

Fixed Panel

Fixed panels are useful for grouping custom content. They include headers and info toolbars.

Fixed panel
Fixed panel

Expandable Panel

Expandable panels are much like fixed panels, except their content can be expanded and collapsed (including the info toolbar, if available).

  • Panel - Expandable2
  • Panel - Expandable1

Components

A panel consists of a title bar with a header text or header toolbar, an info toolbar (optional), and a content area.

The title inside the title bar can be added by using the “headerText” property. If you use the “headerToolbar” aggregation, the “headerText” property is ignored. With the “headerToolbar” aggregation, you can add a toolbar with any toolbar content inside the title bar. For example, if you need a title text on the left and some action buttons on the right, add a title to the toolbar’s content aggregation, toolbar spacer, and then your buttons.

Header toolbar of a panel
Header toolbar of a panel

Behavior and Interaction

Expand/Collapse

  • When the panel is expandable, an arrow icon (pointing to the right) appears in front of the header. Click or tap this icon to expand the panel.
  • When the animation is activated, expand/collapse uses a smooth animation to open or close the content area.
  • When the panel expands, the arrow icon rotates 90 degrees clockwise.
  • When the panel collapses, the arrow icon rotates 90 degrees counterclockwise.
  • The buttons in the header are separately clickable/touchable.

Example

  • Panel - ExpandCollapse1
  • Panel - ExpandCollapse2

Overflow Scrolling (Content Area)

  • When the height uses the default property “auto”, the height of the content area is automatically adjusted to match the height of its content.
  • When the height of the panel is set to a fixed size, the content area can be scrolled through.

Panel With Scrolling

Panel with a fixed height (scrolling activated)
Panel with a fixed height (scrolling activated)

Panel Without Scrolling

Panel with auto height (no scrolling)
Panel with auto height (no scrolling)

Guidelines

  • Nesting two or more panels is not recommended.
  • Do not stack too many panels on one page.

Exceptions

If you add a header toolbar (sap.m.Toolbar) via aggregations, it will overwrite the “headerText” property.

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

  • No links

Panel

The panel is a container for grouping and displaying information. It can be collapsed to save space on the screen.

Usage

  • Use the panel if:

    • You need to group or display information.
    • You want to give users the option of hiding this information.
    • You want to show additional information on demand (for example, a panel could show optional input fields for an advanced search).

Example

  • Panel - Value Search Dialog Closed
  • Panel - Value Search Dialog Open

Responsiveness

If the width of the panel is set to 100% (default), the panel and its children are resized responsively, depending on its parent container.

Layout

  • The panel control is a container for controls.
  • The panel can have a solid or semi-transparent background.
  • The panel always includes a header.
  • An info toolbar can be added to the panel to show extra information.

Examples

Panel with a title toolbar
Panel with a title toolbar
Panel with a title toolbar and infobar
Panel with a title toolbar and infobar

Types

There are two types of panels: fixed and expandable.

Fixed Panel

Fixed panels are useful for grouping custom content. They include headers and info toolbars.

Fixed panel
Fixed panel

Expandable Panel

Expandable panels are much like fixed panels, except their content can be expanded and collapsed (including the info toolbar, if available).

  • Panel - Expandable2
  • Panel - Expandable1

Components

A panel consists of a title bar with a header text or header toolbar, an info toolbar (optional), and a content area.

The title inside the title bar can be added by using the “headerText” property. If you use the “headerToolbar” aggregation, the “headerText” property is ignored. With the “headerToolbar” aggregation, you can add a toolbar with any toolbar content inside the title bar. For example, if you need a title text on the left and some action buttons on the right, add a title to the toolbar’s content aggregation, toolbar spacer, and then your buttons.

Header toolbar of a panel
Header toolbar of a panel

Behavior and Interaction

Expand/Collapse

  • When the panel is expandable, an arrow icon (pointing to the right) appears in front of the header. Click or tap this icon to expand the panel.
  • When the animation is activated, expand/collapse uses a smooth animation to open or close the content area.
  • When the panel expands, the arrow icon rotates 90 degrees clockwise.
  • When the panel collapses, the arrow icon rotates 90 degrees counterclockwise.
  • The buttons in the header are separately clickable/touchable.

Example

  • Panel - ExpandCollapse1
  • Panel - ExpandCollapse2

Overflow Scrolling (Content Area)

  • When the height uses the default property “auto”, the height of the content area is automatically adjusted to match the height of its content.
  • When the height of the panel is set to a fixed size, the content area can be scrolled through.

Panel With Scrolling

Panel with a fixed height (scrolling activated)
Panel with a fixed height (scrolling activated)

Panel Without Scrolling

Panel with auto height (no scrolling)
Panel with auto height (no scrolling)

Styles

Background Design

  • This property is used to set the background color of the panel.
  • Depending on the theme, you can change the state of the background from Solid through Translucent to Transparent.
  • The default value is Translucent.

Example

  • Panel_Style_Translucent
  • Panel_Style_Transparent
  • Panel_Style_Solid

The panel is translucent by default to match the background of the corresponding list, form, table, and so on. These controls also have solid, translucent, and transparent background properties, so it makes sense to give the panel the same type of properties.

This also applies to our own composite controls, such as table personalization, value help, and quick view, which use panels to group standard controls such as input fields and buttons.

Example: In a dialog box with a form-style layout, the background color can be set to transparent so that the input fields in the panel stand out against the background.

A dialog box with form-style layout
A dialog box with form-style layout

Example: A panel with a transparent background used in a table personalization dialog box.

Table personalization dialog box
Table personalization dialog box

Example: A panel with transparent background properties, used in a value help dialog box.

Value help dialog box
Value help dialog box

Example: Quick view (seen here outside the popover or dialog box) is created using translucent panels.

Quick view
Quick view

Guidelines

  • Nesting two or more panels is not recommended.
  • Do not stack too many panels on one page.

Exceptions

If you add a header toolbar (sap.m.Toolbar) via aggregations, it will overwrite the “headerText” property.

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

  • No links

Panel

The panel is a container for grouping and displaying information. It can be collapsed to save space on the screen.

Responsiveness

If the width of the panel is set to 100% (default), the panel and its children are resized responsively, depending on its parent container.

Layout

  • The panel control is a container for controls.
  • The panel can have a solid or semi-transparent background.
  • The panel always includes a header.
  • An info toolbar can be added to the panel to show extra information.

Examples

Types

There are two types of panels: fixed and expandable.

Fixed Panel

Expandable Panel

Components

Guidelines

  • Nesting two or more panels is not recommended.
  • Do not stack too many panels on one page.

Exceptions

If you add a header toolbar (sap.m.Toolbar) via aggregations, it will overwrite the “headerText” property.

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

  • No links

Dynamic Side Content

Dynamic side content is a layout control that allows additional content, such as a timeline, chat, or additional information, to be displayed in a way that flexibly adapts to different screen sizes. App development teams can configure the behavior of the control on smaller screen sizes by following the relevant guidelines.

Dynamic side content layout
Dynamic side content layout

Usage

Use dynamic side content if:

  • You want to display related side-information in addition to the main content. Users should have access to all the key functions and critical information in the app even if they do not see the side content. This is important because on smaller screen sizes it may be difficult to display the side content in a way that is easily accessible for the user.

Do not use dynamic side content if:

  • You want to display critical information in the side content that should go into the main content. The dynamic side content is not meant to split the page into two equally important sections.

Layout

The dynamic side content appears in a container next to or directly below the main content. The side content does not overlay the main content. When the side content is triggered, the main content becomes narrower (if appearing side-by-side). When appearing next to the main content, the side content also contains a separate scrollbar.

Structure of dynamic side content layout
Structure of dynamic side content layout

Responsiveness

The dynamic side content control is built for different screen sizes and layouts. The default screen layout features the side content on the left or right side of the screen, covering 25% of the screen width on a large desktop (over 1440 px).

Dynamic side content – Size S
Dynamic side content – Size S
Dynamic side content – Size M
Dynamic side content – Size M
Dynamic side content – Size L
Dynamic side content – Size L
Responsive behavior of the dynamic side content
Responsive behavior of the dynamic side content

Equal split: A special view of the side content is the 50:50 view, which enables users to show more data, for example, for comparison purposes. The responsive behavior of the equal split is the same as in the standard view: The side content disappears on screen widths of less than 720 px and can only be viewed by triggering it.

On smaller screen sizes (under 1440 px), the side content occupies 33% of the screen width to accommodate the nested controls. If the side content width falls below 320 px, the side content automatically slides under the main content, unless the app development team specifies that it should disappear.

On screen sizes of less than or equal to 720 px, the side content automatically disappears from the screen (unless specified to stay under the content) and can be triggered from a preset trigger (specified within the app). When the side content is triggered, it replaces the main content. We recommend that you always place the trigger for the side content in the same location, such as in the app footer.

The app development team may specify that the side content should slide under the main content when the screen is resized to a smaller width. Sliding the side content under the main content on smaller screens allows it to remain on the screen at all times. However, it may only be accessible via scrolling.

Navigation

The side content is always related to the main content, so it must show content that can be triggered from the main content. This also means minimizing navigation such as drill-ins inside the side content and displaying content that is triggered from the main content area. An example would be showing additional details like contact information or conversation history. If a different type of data relates to the main content, app developers can implement a switcher in the side content. However, we recommend that you keep the side content free of additional navigation elements.

Triggering the side content: The side content can be set to hidden by default, and it automatically disappears when the screen width is less than or equal to 720 px (except when it is set to be under the main content). The app design team can define the trigger point. Our recommendation is to put a transparent text button with a meaningful label in the container toolbar, or an action inside the container the dynamic side content is related to. Ensure that the user can understand how to trigger the side content. Please, avoid using icons, because they can confuse the user.

Hiding the side content: The side content should be hidden from the header (top) section of the side content. The side content container itself has no header. We therefore strongly recommend that you use a toolbar control with a title, a transparent button labeled Close, and a spacer between them.

Hiding side content – From the header section
Hiding side content – From the header section

Guidelines

Use of Controls in the Dynamic Side Content

You can use most of the main controls in the dynamic side content, such as text, simple form, chart, list, panel, tree, timeline, or feed and notes. However, you must make sure that the control doesn’t result in the appearance of a horizontal scrollbar.

Do not use complex controls, such as tables.

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 Side Content

Dynamic side content is a layout control that allows additional content, such as a timeline, chat, or additional information, to be displayed in a way that flexibly adapts to different screen sizes. App development teams can configure the behavior of the control on smaller screen sizes by following the relevant guidelines.

Dynamic side content layout
Dynamic side content layout

Usage

Use dynamic side content if:

  • You want to display relevant information that is not critical for users to complete a task. Users should have access to all the key functions and critical information in the app even if they do not see the side content. This is important because on smaller screen sizes it may be difficult to display the side content in a way that is easily accessible for the user.

Do not use dynamic side content if:

  • You want to display navigation or critical information that prevents users from completing a task when they have no access to the side content.

Layout

The dynamic side content appears in a container next to or directly below the main content. The side content does not overlay the main content. When the side content is triggered, the main content becomes narrower (if appearing side-by-side). When appearing next to the main content, the side content also contains a separate scrollbar.

Structure of dynamic side content layout
Structure of dynamic side content layout

Responsiveness

The dynamic side content control is built for different screen sizes and layouts. The default screen layout features the side content on the left or right side of the screen, covering 25% of the screen width on a large desktop (over 1440 px).

Dynamic side content – Size S
Dynamic side content – Size S
Dynamic side content – Size M
Dynamic side content – Size M
Dynamic side content – Size L
Dynamic side content – Size L
Responsive behavior of the dynamic side content
Responsive behavior of the dynamic side content

Equal split: A special view of the side content is the 50:50 view, which enables users to show more data, for example, for comparison purposes. The responsive behavior of the equal split is the same as in the standard view: The side content disappears on screen widths of less than 720 px and can only be viewed by triggering it.

On smaller screen sizes (under 1440 px), the side content occupies 33% of the screen width to accommodate the nested controls. If the side content width falls below 320 px, the side content automatically slides under the main content, unless the app development team specifies that it should disappear.

On screen sizes of less than or equal to 720 px, the side content automatically disappears from the screen (unless specified to stay under the content) and can be triggered from a preset trigger (specified within the app). When the side content is triggered, it replaces the main content. We recommend that you always place the trigger for the side content in the same location, such as in the app footer.

The app development team may specify that the side content should slide under the main content when the screen is resized to a smaller width. Sliding the side content under the main content on smaller screens allows it to remain on the screen at all times. However, it may only be accessible via scrolling.

Navigation

The side content is always related to the main content, so it must show content that can be triggered from the main content. This also means minimizing navigation such as drill-ins inside the side content and displaying content that is triggered from the main content area. An example would be showing additional details like contact information or conversation history. If a different type of data relates to the main content, app developers can implement a switcher in the side content. However, we recommend that you keep the side content free of additional navigation elements.

Triggering the side content: The side content can be set to hidden by default, and it automatically disappears when the screen width is less than or equal to 720 px (except when it is set to be under the main content). The app design team can define the trigger point. Ensure that the user can understand how to trigger the  side content. If the side content information relates not only to a specific element but also to the entire object, the trigger point should be a link in the footer toolbar. In this case, we strongly recommend that you place the link next to the side content with as few actions as possible between them. Note: This link should be prioritized to prevent it from going into the overflow, where the user might not expect it.

Hiding the side content: The side content should be hidden from the header (top) section of the side content. The side content container itself has no header. We therefore strongly recommend that you use a toolbar control with a title, a transparent button labeled Close, and a spacer between them.

Hiding side content – From the header section
Hiding side content – From the header section

Guidelines

Use of Controls in the Dynamic Side Content

You can use most of the main controls in the dynamic side content, such as text, simple form, chart, list, panel, tree, timeline, or feed and notes. However, you must make sure that the control doesn’t result in the appearance of a horizontal scrollbar.

Do not use complex controls, such as tables.

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 Side Content

Dynamic side content is a layout control that allows additional content, such as a timeline, chat, or additional information, to be displayed in a way that flexibly adapts to different screen sizes. App development teams can configure the behavior of the control on smaller screen sizes by following the relevant guidelines.

Dynamic side content layout
Dynamic side content layout

Usage

Use dynamic side content if:

  • You want to display relevant information that is not critical for users to complete a task. Users should have access to all the key functions and critical information in the app even if they do not see the side content. This is important because on smaller screen sizes it may be difficult to display the side content in a way that is easily accessible for the user.

Do not use dynamic side content if:

  • You want to display navigation or critical information that prevents users from completing a task when they have no access to the side content.

Layout

The dynamic side content appears in a container next to or directly below the main content. The side content does not overlay the main content. When the side content is triggered, the main content becomes narrower (if appearing side-by-side). When appearing next to the main content, the side content also contains a separate scrollbar.

Structure of dynamic side content layout
Structure of dynamic side content layout

Responsiveness

The dynamic side content control is built for different screen sizes and layouts. The default screen layout features the side content on the left or right side of the screen, covering 25% of the screen width on a large desktop (over 1440 px).

Dynamic side content – Size M
Dynamic side content – Size M
Dynamic side content – Size L
Dynamic side content – Size L
Dynamic side content – Size XL
Dynamic side content – Size XL

On smaller screen sizes (under 1440 px), the side content occupies 33% of the screen width to accommodate the nested controls. If the side content width falls below 320 px, the side content automatically slides under the main content, unless the app development team specifies that it should disappear.

On screen sizes of less than or equal to 720 px, the side content automatically disappears from the screen (unless specified to stay under the content) and can be triggered from a preset trigger (specified within the app). When the side content is triggered, it replaces the main content. We recommend that you always place the trigger for the side content in the same location, such as in the app footer.

The app development team may specify that the side content should slide under the main content when the screen is resized to a smaller width. Sliding the side content under the main content on smaller screens allows it to remain on the screen at all times. However, it may only be accessible via scrolling.

Responsive behavior of the dynamic side content
Responsive behavior of the dynamic side content
Closing the side content
Closing the side content

Equal split: A special view of the side content is the 50:50 view, which enables users to show more data, for example, for comparison purposes. The responsive behavior of the equal split is the same as in the standard view: The side content disappears on screen widths of less than 720 px and can only be viewed by triggering it.

Navigation

The side content is always related to the main content. This means that the content shown in the side content must be triggered directly from the main content area. For example, the side content could be used to display additional details such as contact information or conversation history relating to the main content. If a different type of data relates to the main content, app developers can also implement a switcher in the side content. However, we recommend that you keep the side content free of additional navigation elements.

Triggering the Dynamic Side Content

The side content can be set to hidden by default, and it automatically disappears when the screen width is less than or equal to 720 px (except when it is set to be under the main content). The app design team can define the trigger point. Ensure that the user easily understands how to trigger the side content. If the side content information relates not only to a specific element but also to the entire object, the trigger point should be a link in the footer toolbar. In this case, we strongly recommend that you place the link next to the side content with as few actions as possible between them. 

Tip: This link should be prioritized to prevent it from going into the overflow, where the user might not expect it.

Hiding the Dynamic Side Content

The side content should be hidden below the header (top) section of the side content. The side content container itself has no header. We therefore strongly recommend that you use a toolbar control with a title, a transparent button labeled Close, and a spacer between them.

Dynamic side content hidden below the header section
Dynamic side content hidden below the header section

Visual Design

Dynamic side content has no visual design of its own, but app designers and developers should ensure that the margins and padding are similar to the normal page layout. For example, the controls should have the same margins inside the side content container.

Basic layout of the dynamic side content – Size S / side content
Basic layout of the dynamic side content – Size S / side content
Basic layout of the dynamic side content – Size S / roll down
Basic layout of the dynamic side content – Size S / roll down
Basic layout of the dynamic side content – Size M / side content
Basic layout of the dynamic side content – Size M / side content
Basic layout of the dynamic side content – Size M / roll down
Basic layout of the dynamic side content – Size M / roll down
Basic layout of the dynamic side content – Size L / side content
Basic layout of the dynamic side content – Size L / side content

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

Map Container

The map container is a predefined feature set for maps. It fits most use cases and makes it easier for app developers to work with maps.

If you wish to display a geomap or an analytic map without using the map container features, the app developer can also opt to use the analytic map or geomap control.

Components

Overview of map container components
Overview of map container components

The map container includes the following components:

  • A map (geomap or analytic map)
  • Transparent toolbar containing the following buttons:
    • View switch (optional), such as between geomaps and analytic maps
    • Selection menu (optional)
    • Personalization/settings (optional)
    • Full-screen mode
    • Overflow toolbar (generic)
  • A list panel stack, which can be used for a legend or other application-specific content
  • Navigation tools such as:
    • Measure
    • Scale
    • Zoom in/zoom out, including rectangular zoom
    • Home Button

View Switch (optional)

View switches are optional. They allow the user to switch between different map types, charts, and table layouts. You should consider using a view switch for accessibility reasons. For example, users with visual impairments might have a hard time working with subtle color differences or specific color gradients, and might prefer switching to a table view instead.

We recommend using no more than three types of alternate visualization. The segmented button control is used to display the types of visualization available in the view switch, and highlights the type of visualization that is being currently displayed.

The button control gives the user the option to switch between the geomap and analytic map views
The button control gives the user the option to switch between the geomap and analytic map views

Menu for Selection Modes (optional)

The menu for selection modes enables the user to switch between the available selection modes: single, rectangular, and lasso. The button can be hidden.

Selection menu
Selection menu

Personalization (optional)

A personalization button is provided and can be enabled/disabled by the app developer. The corresponding popover and details need to be implemented by the app developer.

The personalization/settings button can be used to show or hide a legend and labels, for example.

Personalization/settings button
Personalization/settings button

Full-Screen Mode

The map container can be viewed on full-screen mode (property: fullScreen). For desktop and tablet, the full-screen button is always placed at the top right of the transparent toolbar.

The user can toggle between embedded and full-screen mode via the maximize full-screen toggle button. In full-screen mode, the map container occupies the entire width and height. The toolbar replaces the page header bar, and the minimize icon appears.

For smartphones, the full-screen button is disabled as the map container is used in full-screen mode by default.

Initiate full-screen button
Initiate full-screen button
Minimize full-screen button
Minimize full-screen button

Overflow (Generic)

The overflow is activated if there is not enough space on the screen for all the chart bar actions. It is generated automatically.

When the user clicks or taps the overflow button, a popover appears. In this action sheet, all icon buttons are labeled with text.

All buttons go into the overflow from right to left.

Overflow button
Overflow button

Prioritization

You can also prioritize the actions in the toolbar by applying one of five different statuses to them:

  • Always overflow: The action will always move into the overflow.
  • Disappear: This applies to actions that are not very relevant for the user, and which can disappear if space is limited.
  • Low: This applies to actions that the user seldom needs; these actions then move first into the overflow.
  • High: These actions remain visible until all actions that are tagged ‘disappear’, ‘low’, or that are untagged, have moved into the overflow.
  • Never overflow: These actions will always visible in the toolbar.

All items have equal priority by default. If two items have the same priority, the one on the right overflows first.

Grouping

Items can overflow together, even if they are in different positions. Elements that belong to a group should not have ‘always overflow’ or ‘never overflow’ statuses as these priorities force the items to remain either in the toolbar or in the overflow area. When group elements have different statuses, the priority of the group is defined by the highest priority of its elements.

List Panel Stack (Optional)

The list panel stack is aligned to the left in the toolbar. It can be used for a legend and other application-specific content. The list panel stack can be collapsed in a way that only the icons of the different list panels will be seen. We recommend using icons that are easy to understand for each panel, as these icons will be the only visible element when the panels are collapsed. The collapsed list panels serve as quick access to the clicked panel icon.

If you are not using icons for the panels, do not allow the panels to collapse.

The default width of the list panel stack is auto. We recommend defining a precise width to avoid having the width permanently change according to the content. The list panel stack will remain visible on the map, whereas the toolbar buttons will be hidden.

As a general rule, avoid using too many panels as too much scrolling will increase the complexity of the application.

The list panel provides the same features as the standard list item:

  • Grouping
  • Select items
  • Include Icons/color markers or pictures
  • Show counter
Collapsed list panel stack (desktop)
Collapsed list panel stack (desktop)
Expanded list panel stack (desktop)
Expanded list panel stack (desktop)

Legend

We recommend to include the map legend in the list panel. All necessary features for a legend are provided through the list panel stack (see above).

If your specific use case does not allow you to include the legend in the list panel, you can also use the map legend.

Navigation Tools

Zoom In/ Zoom Out

The map container provides zoom in ( ) and zoom out ( ) buttons, which are positioned bottom right of the map. When the user clicks or taps the zoom in or zoom out icon, the chart automatically zooms in or out to the most appropriate scale.

By default, the ‘ ’ and ‘ ‘ buttons are enabled.

Zoom in and out button
Zoom in and out button

Rectangular Zoom

The rectangular zoom can be used to zoom to a specific position. The rectangular zoom is enabled for the compact form factor by default, and disabled for the cozy form factor. Learn more about content density factors here.

Rectangular zoom button
Rectangular zoom button

Home Button

The map container provides a Home button. Clicking on the Home button leads to the initial zoom position.

Home button
Home button

Responsiveness & Adaptiveness

The width and height of the map container are defined by the surrounding application layout.

The map container uses the overflow toolbar control. This control is based on the sap.m.Toolbar and provides overflow when the contents do not fit in the visible area.

Map container displayed on a desktop
Map container displayed on a desktop
The map container is displayed on a smartphone. Because of the small screen size, the list panel stack is displayed as a menu button.
The map container is displayed on a smartphone. Because of the small screen size, the list panel stack is displayed as a menu button.
The map container displayed on a tablet.
The map container displayed on a tablet.

Behavior and Interaction

For overflow, the buttons have default priority. The application developer can change this priority. High-prioritized buttons will overflow last.

On desktop and tablet, the list panel stack will always be visible, whereas the transparent toolbar overflows. The navigation control will hide behind the panel list stack.

On a smartphone, the list panel stack is minimized to a menu button on the top left. The menu icon always remains on the screen, whereas the transparent toolbar buttons overflow. Clicking on the menu button, the list panel stack opens in full screen mode.

We generally recommend using either icon buttons or text buttons within the transparent toolbar, but not both. Icons and text should not be combined into one button. Buttons with icon and text appear only in the overflow menu. Buttons are always aligned to the right.

Guidelines

  • Think carefully about what actions you really need in the transparent map toolbar – do not overload the map toolbar with actions.
  • Think carefully about what content you really need in the panel list stack – do not overload the panel with content.
  • Think carefully about which features make sense on the map if the map is not used in full screen. For example, it wouldn’t make sense for a map to have a list panel stack if it is being featured on a card of an overview page.
  • Use tooltips for switchable content. For example, label icon buttons as “geomap” or “analytic map” in the toolbar.

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

Implementation

No Links.