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.
Items Empty Span
By default, a form item spans 12 cells, fully divided between its label and field, with no empty space at the end:
- Label: occupies 4 cells.
- Field: occupies 8 cells.
The emptySpan property provides additional layout flexibility by defining empty space at the form item’s end.
For example: Setting "S0 M0 L3 XL3" (or just "L3 XL3") adjusts the layout as follows:
- Label: remains 4 cells.
- Field: is reduced to 5 cells.
- Empty space: 3 cells are added at the end.
Greater values increase the empty space at the end of the form item, reducing the space available for the label and its field.
However, setting emptySpan to 1 cell is recommended and typically sufficient to achieve a balanced layout.
Navigation flow
The Form component supports two layout options for keyboard navigation:
Simple form
In this "simple form" layout, each ui5-form-item acts as a standalone group
with one item, so focus moves horizontally across the grid from one ui5-form-item to the next.
This layout is ideal for simpler forms and supports custom arrangements, e.g.,
| 1 | 2 |
| 3 |
| 4 | 5 |
Complex form
In this layout, items are grouped into ui5-form-group elements, allowing more complex configurations:
-
Single-Column Group: Focus moves vertically down from one item to the next.
| 1 |
| 2 |
| 3 | -
Multi-Column Group: Focus moves horizontally within each row, advancing to the next row after completing the current one.
| 1 | 4 |
| 2 | 5 |
| 3 | 6 |
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
emptySpan
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 labelSpan property to define the width proportion of the labels and fields of a FormItem by breakpoint.
For example:
- 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)
Empty Span
Use the emptySpan property to define the empty space at the FormItem's end.
For example:
- emptySpan="S1 M1 L1 XL1" + labelSpan="S4 M4 L4 XL4" will define "4 | 7 | 1" proportion between the label, the field and the empty space
- emptySpan="S3 M3 L3 XL3" + labelSpan="S4 M4 L4 XL4" will define "4 | 5 | 3" proportion between the label, the field and the empty space
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.