Docs

Docs

Form Layout

Source: TypeScript / Java
Using Form Layout to build responsive forms with multiple columns and better positioned input labels.

Form Layout allows you to build responsive forms with multiple columns, and to position input labels above or to the side of the input.

Open in a
new tab
TextField firstName = new TextField("First name");
TextField lastName = new TextField("Last name");
EmailField email = new EmailField("Email address");
PasswordField password = new PasswordField("Password");
PasswordField confirmPassword = new PasswordField("Confirm password");

FormLayout formLayout = new FormLayout();
formLayout.setAutoResponsive(true);
formLayout.addFormRow(firstName, lastName);
formLayout.addFormRow(email);
formLayout.addFormRow(password, confirmPassword);

Form Layout automatically adjusts how fields are laid out in columns and rows to utilize the available space and avoid overflow. There are two discrete layouting modes that determine how this works:

Note
Default mode depends on feature flag
In V24.8+, the default mode depends on the feature flag defaultAutoResponsiveFormLayout. When enabled, auto-responsive mode is the default; otherwise, responsive steps mode is the default.

Auto-Responsive Mode

In auto-responsive mode, Form Layout automatically determines the appropriate number of columns based on the column width and spacing, and the available horizontal space.

formLayout.setAutoResponsive(true);
Note
Feature Flag Controls Default Mode
In V24.8+, auto-responsive mode can be set as default by setting the feature flag defaultAutoResponsiveFormLayout to true. This is recommended for new projects as auto-responsive will be the default mode in V25.

The sections below describe features available in auto-responsive mode.

Form Rows

In auto-responsive mode, all fields are laid out in a single column by default. To render multiple fields side-by-side, i.e. in multiple columns, they can be grouped into Form Rows.

Open in a
new tab
TextField firstName = new TextField("First name");
TextField lastName = new TextField("Last name");
EmailField email = new EmailField("Email address");
PasswordField password = new PasswordField("Password");
PasswordField confirmPassword = new PasswordField("Confirm password");

FormLayout formLayout = new FormLayout();
formLayout.setAutoResponsive(true);
formLayout.addFormRow(firstName, lastName);
formLayout.addFormRow(email);
formLayout.addFormRow(password, confirmPassword);

Form Rows automatically wrap their contents into multiple rows if the layout doesn’t have enough columns to fit them on a single row.

Note
UX Tip: Group Related Fields Into Rows
Forms are easier to understand if fields are grouped into rows based on how closely related they are, rather than arbitrarily. As an example, first name and last name are typically placed on the same row, while a date-of-birth field would typically be on a different row.

Label Position

By default, labels are rendered above the field. Labels can be rendered next to the field by wrapping fields into Form Items and switching to labels-aside mode.

Open in a
new tab
TextField firstName = new TextField();
TextField lastName = new TextField();
EmailField email = new EmailField();

FormLayout formLayout = new FormLayout();
formLayout.setAutoResponsive(true);
formLayout.setLabelsAside(true);
formLayout.addFormItem(firstName, "First name");
formLayout.addFormItem(lastName, "Last name");
formLayout.addFormItem(email, "Email address");

The field label must be applied on the Form Item rather than the field itself.

When the Form Layout’s width isn’t sufficient to render labels next to fields, it automatically reverts back to rendering them above fields.

Note
UX Tip: Labels Aside Work Best In Single Column Forms
Forms with labels next to the fields can be confusing if fields are rendered in multiple columns. Although Form Layout supports combining side-labels with multiple columns, this combination is not recommended.

The width of side labels can be configured with the --vaadin-form-item-label-width CSS property. The Flow API also has a dedicated setLabelWidth API for this.

Column Width

All columns in a Form Layout have the same width, which can be configured to any CSS length value in absolute or font-relative units like px, pt, em, rem, or ch (percentages and length keywords like auto or min-content are not supported).

formLayout.setColumnWidth("8em");

Additionally, columns can be set to expand to fill any remaining available space in the layout:

Open in a
new tab
TextField firstName = new TextField("First name");
TextField lastName = new TextField("Last name");
EmailField email = new EmailField("Email");
PasswordField password = new PasswordField("Password");
PasswordField confirmPassword = new PasswordField("Confirm password");

FormLayout formLayout = new FormLayout();
formLayout.setAutoResponsive(true);
formLayout.setColumnWidth("8em");
formLayout.setExpandColumns(true);
formLayout.addFormRow(firstName, lastName);
formLayout.addFormRow(email);
formLayout.addFormRow(password, confirmPassword);

This is typically combined with expanding fields to fill the full width of their columns, as described below.

Expanding Fields to Fill Their Columns

In auto-responsive mode, fields do not fill the columns they’re in by default (although they are prevented from overflowing them). This can be changed by enabling field expansion:

Open in a
new tab
TextField firstName = new TextField("First name");
TextField lastName = new TextField("Last name");
EmailField email = new EmailField("Email");
PasswordField password = new PasswordField("Password");
PasswordField confirmPassword = new PasswordField("Confirm password");

FormLayout formLayout = new FormLayout();
formLayout.setAutoResponsive(true);
formLayout.setColumnWidth("8em");
formLayout.setExpandColumns(true);
formLayout.setExpandFields(true);
formLayout.addFormRow(firstName, lastName);
formLayout.addFormRow(email);
formLayout.addFormRow(password, confirmPassword);

If only certain fields should expand, this can be achieved by setting their widths to 100%.

Note
UX Tip: Fields Should Match Their Typical Content Length
Although a uniform field size may look nice, matching field widths to the typical length of their contents makes it easier to find the correct field and the form easier to understand. This can be achieved by leaving field expansion disabled, or by using column span to determine the relative widths of fields.

Column Limit

The number of columns can be limited by setting the maximum column count.

formLayout.setMaxColumns(3);

Responsive Steps Mode

In responsive steps mode, columns are defined explicitly for a number of breakpoints, or steps, based on the layout’s width, and fields are automatically laid out in the available columns, wrapping to the next row as needed.

The default breakpoint configuration is one column below a layout width of 40em, and two columns above that.

Note
Feature Flag Controls Default Mode
In V24.8+, the feature flag defaultAutoResponsiveFormLayout makes auto-responsive mode the default. With the flag enabled, individual Form Layouts can be switched to responsive steps mode by defining the responsive steps manually.

Setting the Breakpoints

Each breakpoint defines the minimum layout width at which it is applied, and the number of columns rendered.

The following example sets

  • One column when the layout is less than 320 pixels wide

  • Two columns when the layout is at least 320 pixels wide

  • Three columns when the layout is at least 500 pixels wide

Open in a
new tab
TextField firstName = new TextField("First name");
TextField lastName = new TextField("Last name");
EmailField email = new EmailField("Email address");

FormLayout formLayout = new FormLayout();
formLayout.add(firstName, lastName, email);
formLayout.setResponsiveSteps(
        // Use one column by default
        new ResponsiveStep("0", 1),
        // Use two columns, if the layout's width exceeds 320px
        new ResponsiveStep("320px", 2),
        // Use three columns, if the layout's width exceeds 500px
        new ResponsiveStep("500px", 3));

Note that

  • The smallest breakpoint should always be at zero pixels;

  • The breakpoints must be ordered by width.

Label Position

By default, labels are rendered above the field. Labels can be rendered next to the field by wrapping the fields into Form Items.

In responsive steps mode, fields wrapped in Form Items render their fields on the side by default, unless the breakpoint configuration defines the label position to be above the fields.

Open in a
new tab
TextField firstName = new TextField();
TextField lastName = new TextField();
EmailField email = new EmailField();

FormLayout formLayout = new FormLayout();
formLayout.setLabelWidth("92px");
formLayout.addFormItem(firstName, "First name");
formLayout.addFormItem(lastName, "Last name");
formLayout.addFormItem(email, "Email address");

// This is the default configuration shown for demonstration purposes
// formLayout.setResponsiveSteps(
//         new ResponsiveStep("0", 1, ResponsiveStep.LabelsPosition.TOP),
//         new ResponsiveStep("20em", 1),
//         new ResponsiveStep("40em", 2));

The default breakpoint configuration renders Form Item wrapped fields with labels on the side, but reverts to labels above fields when the layout is less than 20em wide.

Note that

  • The field label must be applied on the Form Item rather than the field itself.

  • Fields wrapped into Form Items do not match the size of the wrapper by default. To avoid empty space or overflow in the column, set the widths of the fields to 100%.

Note
UX Tip: Labels Aside Work Best In Single Column Forms
Forms with labels next to the fields can be confusing if fields are rendered in multiple columns. Although Form Layout supports combining side-labels with multiple columns, this combination is not recommended.

Row Breaks

Fields can be forced to break into multiple rows using html <br> line break elements:

formLayout.add(new TextField("First name"));
formLayout.add(new TextField("Last name"));
formLayout.add(ElementFactory.createBr()); // row break
formLayout.add(new EmailField("Email address"));

Field Width

In responsive steps mode, fields are automatically scaled to fit and fill the columns. Overriding this by setting minimum or maximum width on the field breaks the layout.

To prevent a field from stretching to fill the full width of the column, wrap it in a Form Item. Note that the field may overflow the Form Item and break the layout if its width is larger than the width of the column. To avoid this, set the field’s maximum width to 100%.

Column Span

Fields can span multiple columns. Note that fields wrapped into Form Items must have their columns span set on the Form Item instead of the field itself.

Open in a
new tab
TextField streetAddress = new TextField("Street address");
TextField postalCode = new TextField("Postal code");
TextField city = new TextField("City/Town");
TextField country = new TextField("Country");

FormLayout formLayout = new FormLayout();
formLayout.setAutoResponsive(true);
formLayout.setExpandFields(true);
formLayout.setColumnWidth("8em");

FormRow firstRow = new FormRow();
firstRow.add(streetAddress, 3); // colspan 3

FormRow secondRow = new FormRow();
secondRow.add(postalCode);
secondRow.add(city, 2); // colspan 2

FormRow thirdRow = new FormRow();
thirdRow.add(country, 2); // colspan 2

formLayout.add(firstRow, secondRow, thirdRow);

Column span is capped to the number of columns currently in the layout to prevent overflow.

Spacing

Form Layout allows you to configure the spacing between columns, rows, and between the label and input field when labels are positioned on the side.

Use the following CSS properties on individual vaadin-form-layout elements, or globally on the html element. The Flow API also provides setters for these properties.

Spacing CSS Property Flow API

Between columns

--vaadin-form-layout-column-spacing

setColumnSpacing

Between rows

--vaadin-form-layout-row-spacing

setRowSpacing

Between side label and field

--vaadin-form-layout-label-spacing

setLabelSpacing

Miscellaneous

Form Item Usage

Form Item is only intended for wrapping individual input field components or native html <input> elements. It automatically applies an aria-labelledby attribute to the element for screen reader support, which only works correctly with input fields and Web Components with an ariaTarget property that returns an appropriate element to which the aria-labelledby attribute can be applied.

To combine multiple inputs in the same form field, or to provide a label to other elements that lack labels, use Custom Field instead. A Custom Field can be further wrapped into a Form Item for side-label support.

Scrolling

Form Layout does not provide its own scroll area. To make a scrollable form, wrap the layout into a Scroller, and make sure that its size is undefined in the desired scroll direction.

Field Focus Order

Fields in multi-column Form Layouts always flow from left to right, then down, and the focus order of the fields will match this order. To make a form where focus flows from top to bottom, column by column, split the form into multiple single-column Form Layouts instead.

Buttons

Forms usually have buttons at the bottom for saving or cancelling changes. While these can be placed in the Form Layout itself, it is usually better to put them in a separate layout below the Form Layout. The Button component documentation provides more recommendations on buttons in forms.

7B8E4F98-540C-4622-A39F-907C95E9DFFD