Form Layout

Columns
Label Position
Native Input Fields
Best Practises

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

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

FormLayout formLayout = new FormLayout();
formLayout.add(
        firstName, lastName,
        username,
        password, confirmPassword
);
formLayout.setResponsiveSteps(
        // Use one column by default
        new ResponsiveStep("0", 1),
        // Use two columns, if layout's width exceeds 500px
        new ResponsiveStep("500px", 2)
);
// Stretch the username field over 2 columns
formLayout.setColspan(username, 2);

Columns

Form Layout has two columns by default meaning it displays two input fields per line. When the layout width is smaller it adjusts to a single column layout.

Custom Layout

You can define how many columns Form Layout should use based on the screen width.

Important

Use the draggable split handle to resize Form Layout’s available space and test its responsiveness.

Open in a
new tab
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)
);

A single column layout is preferable to a multi column one. A multi column layout is more prone to cause confusion and to be misinterpreted by the user.

However, closely related fields can be placed in line without issue. For example, first and last name, address fields such as postal code and city, as well as ranged input for dates, time, currency, etc.

Column Span

When using a multi column layout you can define a colspan for each component. colspan determines how many columns a component extends or stretches across.

For example, if you have a Form Layout with three columns and a component’s colspan is set to three, it takes up the entire width of the Form Layout.

Open in a
new tab
formLayout.setColspan(title, 3);

Label Position

Input fields' built-in labels are positioned above the input. Form Layout supports side positioned labels provided they are wrapped in Form Items and the label position is set to aside.

The only reason for wrapping labels in Form Items is to put the labels to the side of the input.

Top

Forms using top-positioned labels generally produce faster completion rates because they provide a consistent scanning pattern (top-down as opposed to a zig-zag) while minimizing the distance between the label and input.

Top-positioned labels are also less prone to cause layout issues due to variable label lengths as is the case of multilingual applications.

They do however result in vertically longer forms which is why sectioning is important.

Side

Side-positioned labels help reduce a form’s overall height. This is especially useful for longer forms and/or when vertical space is limited. They’re also often used when there is a need to compare numeric data.

Open in a
new tab
// Use addFormItem instead of add, to wrap fields into form items,
// which displays labels on the side by default
formLayout.addFormItem(revenue, "Revenue");
formLayout.addFormItem(expenses, "Expenses");
formLayout.addFormItem(invoices, "Invoices");

Aim for similar length labels to keep the distance between the labels and input fields consistent. Inconsistent spacing can cause slower completion rates.

Forms using this position require more horizontal space which isn’t always ideal in narrow forms. It’s recommended to configure Form Layout to use top-positioned labels when the form’s width is small.

Caution

Accessibility

Form Item suffers from two accessibility issues: required indicators cannot be displayed and screen readers are unable to announce a field’s label.

Responsive Label Position

Like the number of columns, the label position is configurable based on the layout’s width. For example, you can position the labels on the side when there’s ample horizontal space available, and on top on narrower screens.

Native Input Fields

Form Item allows you to set a label for any type of component that you want to use in a Form Layout. It supports both Vaadin components and native HTML components.

Open in a
new tab
formLayout.addFormItem(new Input(), "Revenue");

Best Practises

Sectioning

Longer forms should be split into smaller, more manageable and user-friendly sections using subheadings, Tabs, Details or separate views when possible. Each section should consist of related content and/or fields.

Button Placement

Use the following guidelines for Button placement in forms:

Buttons should be placed below the form they’re associated with.
Buttons should be aligned left.
Primary action first, followed by other actions, in order of importance.

For more information, please see the Button documentation.

93D072C8-B1CC-4BF4-B110-592CFDA11E43

Docs