Form
<ui5-form> | Since 2.0.0This component is availabe since 2.0 under an experimental flag and its API and behaviour are subject to change.
The Form is a layout component that arranges labels and form fields (like input fields) pairs into a specific number of columns.
Note: The Form web component is a layout component, it isn't a replacement for the native form HTML element.
The Form web component does not provide any APIs for form submission.
Structure​
- Form (
ui5-form) is the top-level container component, responsible for the content layout and responsiveness. - FormGroup (
ui5-form-group) enables the grouping of the Form content. - FormItem (
ui5-form-item) is a pair of label and form fields and can be used directly in a Form, or as part of a FormGroup.
The simplest Form (ui5-form) consists of a header area on top,
displaying a header text (see the headingText property) and content below - an arbitrary number of FormItems (ui5-form-item),
representing the pairs of label and form fields.
And, there is also "grouping" available to assist the implementation of richer UIs.
This is enabled by the FormGroup (ui5-form-group) component.
In this case, the Form is structured into FormGroups and each FormGroup consists of FormItems.
Responsiveness​
The Form component reacts and changes its layout on predefined breakpoints. Depending on its size, the Form content (FormGroups and FormItems) gets divided into one or more columns as follows:
- S (< 600px) – 1 column is recommended (default: 1)
- M (600px - 1022px) – up to 2 columns are recommended (default: 1)
- L (1023px - 1439px) - up to 3 columns are recommended (default: 2)
- XL (> 1439px) – up to 6 columns are recommended (default: 3)
To change the layout, use the layout property - f.e. layout="S1 M2 L3 XL6".
Groups​
To make better use of screen space, there is built-in logic to determine how many columns should a FormGroup occupy.
-
Example #1 (perfect match): 4 columns and 4 groups: each group will use 1 column.
-
Example #2 (balanced distribution): 4 columns and 2 groups: each group will use 2 columns. 6 columns and 2 groups: each group will use 3 columns.
-
Example #3 (unbalanced distribution): 3 columns and 2 groups: the larger one will use 2 columns, the smaller 1 column. 5 columns and 3 groups: two of the groups will use 2 columns each, the smallest 1 column.
Note: The size of a group element is determined by the number of FormItems assigned to it. In the case of equality, the first in the DOM will use more columns, and the last - fewer columns.
- Example #4 (more groups than columns): 3 columns and 4 groups: each FormGroup uses only 1 column, the last FormGroup will wrap on the second row.
Groups Column Span​
To influence the built-in group distribution, described in the previous section,
you can use the FormGroup's columnSpan property, that defines how many columns the group should expand to.
Items Column Span​
FormItem's columnSpan property defines how many columns the form item should expand to inside a form group or the form.
Items Label Span​
The placement of the labels depends on the size of the used column.
If there is enough space, the labels are next to their associated fields, otherwise - above the fields.
By default, the labels take 4/12 of the FormItem, leaving 8/12 parts to associated fields.
You can control what space the labels should take via the labelSpan property.
For example: To always place the labels on top set: labelSpan="S12 M12 L12 XL12" property.
Keyboard Handling​
- [Tab] - Moves the focus to the next interactive element within the Form/FormGroup (if available) or to the next element in the tab chain outside the Form
- [Shift] + [Tab] - Moves the focus to the previous interactive element within the Form/FormGroup (if available) or to the previous element in the tab chain outside the Form
- [F6] - Moves the focus to the first interactive element of the next FormGroup (if available) or to the next element in the tab chain outside the Form
- [Shift] + [F6] - Moves the focus to the first interactive element of the previous FormGroup (if available) or to the previous element in the tab chain outside the Form
ES6 Module Import​
- import @ui5/webcomponents/dist/Form.js";
- import @ui5/webcomponents/dist/FormGroup.js";
- import @ui5/webcomponents/dist/FormItem.js";
Basic Sample​
Properties​
layout​
labelSpan​
headerText​
itemSpacing​
Slots​
header​
default​
Events​
No events available for this component.
Methods​
No methods available for this component.
CSS Parts​
More Samples​
Layout​
Use the Form#layout property to define the number of columns to distribute the form content by breakpoint.
- S1 M1 L2 XL3 - 1 cols in S, 1 cols in M, 2 cols in L and 3 cols in XL (default layout)
- S1 M2 L3 XL5 - 1 cols in S, 2 cols in M, 3 cols in L and 5 cols in XL
- S1 M2 L4 XL6 - 1 cols in S, 2 cols in M, 4 cols in L and 6 cols in XL
- S2 M3 L5 XL7 - 2 cols in S, 3 cols in M, 5 cols in L and 7 cols in XL
Groups​
You can define groups via the ui5-form-group web component.
Label Span​
Use the Form#labelSpan property to define the width proportion of the labels and fields of a FormItem by breakpoint.
- S12 M4 L4 XL4 - the label takes 1/3 in M, L, XL
- S12 M6 L6 XL6 - the label takes 1/2 in M, L, XL
- S12 M12 L12 XL12 - the label takes the whole line and the texts gows on the next line (in all sizes)
Labels On Top​
Force labels always on top Form#labelSpan=S12 M12 L12 XL12.
Edit​
The Form has no built-in functionality to transform texts into inputs to implement editable forms. This is delegated to the consumers as shown in the sample. Note: We recommend using "Large" item spacing in "display" mode, and "Normal" for "edit" mode, to avoid "jumping" effect of switching between texts and inputs.
Column Span​
FormGroup#columnSpan​
The FormGroup#columnSpan property defines how many columns the form group should expand to.
FormItem#columnSpan​
The FormItem#columnSpan defines to how many columns the form item should expand to.
Header Text Wrapping​
The Form header text is wrapping when doesn't fit the available space.
Custom Header​
The Form provides a header slot that allows the usage of custom form header.