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

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

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

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.

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.

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

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.

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.