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:

• Form – sap.ui.layout.form.Form (API)
• Simple form – sap.ui.layout.form.SimpleForm (API)

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.

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

Layout

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.

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)

Size M (Tablet) – Full Screen

Size L (Desktop Screens)

Size XL (Desktop Wide Screens)

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.

Use of Columns

Components

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

• Button and segmented button
• Checkbox
• File uploader
• Icon
• Image
• Input controls, such as the combo box, multi-combo box, date picker, date/time picker, dynamic date, time picker, input field, multi-input field, and mask input.
• Object number
• Object status
• Progress indicator
• Radio button and radio button group
• Rating indicator
• Search field
• Select
• Slider
• Step input
• Switch
• Text and text area

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.

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.

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.