Package com.vaadin.flow.component.formlayout

Class FormLayout

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.formlayout.FormLayout
All Implemented Interfaces:
AttachNotifier, ClickNotifier<FormLayout>, DetachNotifier, HasComponents, HasElement, HasEnabled, HasSize, HasStyle, Serializable
@Tag("vaadin-form-layout") @NpmPackage(value="@vaadin/polymer-legacy-adapter",version="24.8.0") @NpmPackage(value="@vaadin/form-layout",version="24.8.0") @JsModule("@vaadin/polymer-legacy-adapter/style-modules.js") @JsModule("@vaadin/form-layout/src/vaadin-form-layout.js") public class FormLayout extends Component implements HasSize, HasStyle, HasComponents, ClickNotifier<FormLayout>
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. 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.

You can define how many columns Form Layout should use based on the screen width. 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.

Best Practices:
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.

Also, 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.

Auto Responsive Mode

To avoid manually dealing with responsive breakpoints, Form Layout provides an auto-responsive mode that automatically creates and adjusts fixed-width columns based on the container's available space.

To control the number of columns and their widths, you can use the following properties:

  • columnWidth - controls the column width (13em by default).
  • maxColumns - controls the maximum number of columns that the layout can create (10 by default).
  • minColumns - controls the minimum number of columns that the layout will create (1 by default).

The auto-responsive mode is disabled by default. To enable it for an individual instance, set the autoResponsive property to true: 

 FormLayout formLayout = new FormLayout();
 formLayout.setAutoResponsive(true);
 formLayout.add(new TextField("First name"), new TextField("Last name"));
 formLayout.add(new TextArea("Address"), 2); // colspan 2

You can also enable it for all instances by enabling the following feature flag in src/main/resources/vaadin-featureflags.properties: 

 com.vaadin.experimental.defaultAutoResponsiveFormLayout = true

Organizing Fields into Rows

By default, each field is placed on a new row. To organize fields into rows, you can either:

  • Manually wrap fields into FormLayout.FormRow elements.
  • Enable the autoRows property to let Form Layout automatically arrange fields in available columns, wrapping to a new row when necessary. HTML br elements can be used to force a new row.

Here is an example of using FormLayout.FormRow: 

 FormLayout formLayout = new FormLayout();
 formLayout.setAutoResponsive(true);

 FormRow firstRow = new FormRow();
 firstRow.add(new TextField("First name"), new TextField("Last name"));

 FormRow secondRow = new FormRow();
 secondRow.add(new TextArea("Address"), 2); // colspan 2

 formLayout.add(firstRow, secondRow);

Expanding Columns and Fields

You can configure Form Layout to expand columns to evenly fill any remaining space after all fixed-width columns have been created. To enable this, set the expandColumns property to true.

Also, Form Layout can stretch fields to make them take up all available space within columns. To enable this, set the expandFields property to true.

Customizing Label Position

By default, Form Layout displays labels above the fields. To position labels beside fields, you need to wrap each field in a FormLayout.FormItem element and define its labels on the wrapper. Then, you can enable the labelsAside property: 

 FormLayout formLayout = new FormLayout();
 formLayout.setAutoResponsive(true);
 formLayout.setLabelsAside(true);

 FormRow firstRow = new FormRow();
 firstRow.addFormItem(new TextField(), "First Name");
 firstRow.addFormItem(new TextField(), "Last Name");

 FormRow secondRow = new FormRow();
 FormItem addressField = secondRow.addFormItem(new TextArea(), "Address");
 secondRow.setColspan(addressField, 2);

 formLayout.add(firstRow, secondRow);

With this, FormLayout will display labels beside fields, falling back to the default position above the fields only when there isn't enough space.

Author:
Vaadin Ltd
See Also:

  • Constructor Details

  • Method Details

    • setColspan

      public void setColspan(Component component, int colspan)
      Sets the colspan of the given component's element. Will default to 1 if an integer lower than 1 is supplied. You can directly add components with the wanted colspan with add(Component, int).
      Parameters:
      component - the component to set the colspan for, not null
      colspan - the desired colspan for the component

    • add

      public void add(Component component, int colspan)
      Adds a component with the desired colspan. This method is a shorthand for calling HasComponents.add(Component...) and setColspan(Component, int)
      Parameters:
      component - the component to add
      colspan - the desired colspan for the component

    • getColspan

      public int getColspan(Component component)
      Gets the colspan of the given component. If none is set, returns 1.
      Parameters:
      component - the component whose colspan is retrieved
      Returns:
      the colspan of the given component or 1 if none is set

    • getResponsiveSteps

      public List<FormLayout.ResponsiveStep> getResponsiveSteps()
      Get the list of FormLayout.ResponsiveSteps used to configure this layout.
      Returns:
      the list of FormLayout.ResponsiveSteps used to configure this layout
      See Also:

    • setResponsiveSteps

      public void setResponsiveSteps(List<FormLayout.ResponsiveStep> steps)
      Configure the responsive steps used in this layout.

      NOTE: Responsive steps are ignored in auto-responsive mode, which may be enabled explicitly via setAutoResponsive(boolean) or implicitly if the following feature flag is set in src/main/resources/vaadin-featureflags.properties: 

       com.vaadin.experimental.defaultAutoResponsiveFormLayout = true
      Parameters:
      steps - list of FormLayout.ResponsiveSteps to set
      See Also:

    • setResponsiveSteps

      public void setResponsiveSteps(FormLayout.ResponsiveStep... steps)
      Configure the responsive steps used in this layout.

      NOTE: Responsive steps are ignored in auto-responsive mode, which may be enabled explicitly via setAutoResponsive(boolean) or implicitly if the following feature flag is set in src/main/resources/vaadin-featureflags.properties: 

       com.vaadin.experimental.defaultAutoResponsiveFormLayout = true
      Parameters:
      steps - the FormLayout.ResponsiveSteps to set
      See Also:

    • addFormItem

      public FormLayout.FormItem addFormItem(Component field, String label)
      Convenience method for creating and adding a new FormItem to this layout that wraps the given field with a label. Shorthand for addFormItem(field, new Label(label)).
      Parameters:
      field - the field component to wrap
      label - the label text to set
      Returns:
      the created form item
      See Also:

    • addFormItem

      public FormLayout.FormItem addFormItem(Component field, Component label)
      Convenience method for creating and adding a new FormItem to this layout that wraps the given field with a component as its label.
      Parameters:
      field - the field component to wrap
      label - the label component to set
      Returns:
      the created form item

    • addFormRow

      public FormLayout.FormRow addFormRow(Component... components)
      Convenience method dor creating and adding a new FormLayout.FormRow to this layout. The method accepts a list of components that will be added to the row.
      Parameters:
      components - the components to add to the row
      Returns:
      the created form row

    • setLabelWidth

      public void setLabelWidth(String width)
      Sets the width of side-positioned label.
      Parameters:
      width - the value and CSS unit as a string
      See Also:

    • setLabelWidth

      public void setLabelWidth(float width, Unit unit)
      Sets the width of side-positioned label.
      Parameters:
      width - the value of the width
      unit - the CSS unit of the width
      See Also:

    • getLabelWidth

      public String getLabelWidth()
      Gets the width of side-positioned label.
      Returns:
      the value and CSS unit as a string
      See Also:

    • setLabelSpacing

      public void setLabelSpacing(String labelSpacing)
      Sets the gap between the label and the field which is used when labels are positioned aside. The value must be provided in CSS length units, e.g. 1em.
      Parameters:
      labelSpacing - the gap between the label and the field
      See Also:

    • setLabelSpacing

      public void setLabelSpacing(float labelSpacing, Unit unit)
      Sets the gap between the label and the field which is used when labels are positioned aside. The value must be provided with a Unit, e.g., 1 and Unit.EM.
      Parameters:
      labelSpacing - the gap between the label and the field
      unit - the CSS unit of the gap
      See Also:

    • getLabelSpacing

      public String getLabelSpacing()
      Gets the gap between the label and the field which is used when labels are positioned aside.
      Returns:
      the value and CSS unit as a string
      See Also:

    • setColumnSpacing

      public void setColumnSpacing(String columnSpacing)
      Sets the gap between the columns. The value must be provided in CSS length units, e.g. 1em.
      Parameters:
      columnSpacing - the gap between the columns
      See Also:

    • setColumnSpacing

      public void setColumnSpacing(float columnSpacing, Unit unit)
      Sets the gap between the columns. The value must be provided with a Unit, e.g. 1 and Unit.EM.
      Parameters:
      columnSpacing - the gap between the columns
      unit - the CSS unit of the gap
      See Also:

    • getColumnSpacing

      public String getColumnSpacing()
      Gets the gap between the columns.
      Returns:
      the value and CSS unit as a string
      See Also:

    • setRowSpacing

      public void setRowSpacing(String rowSpacing)
      Sets the gap between the rows. The value must be provided in CSS length units, e.g. 1em.
      Parameters:
      rowSpacing - the gap between the rows
      See Also:

    • setRowSpacing

      public void setRowSpacing(float rowSpacing, Unit unit)
      Sets the gap between the rows. The value must be provided with a Unit, e.g., 1 and Unit.EM.
      Parameters:
      rowSpacing - the gap between the rows
      unit - the CSS unit of the gap
      See Also:

    • getRowSpacing

      public String getRowSpacing()
      Gets the gap between the rows.
      Returns:
      the value and CSS unit as a string
      See Also:

    • setAutoResponsive

      public void setAutoResponsive(boolean autoResponsive)
      When set to true, the component automatically creates and adjusts columns based on the container's width. Columns have a fixed width defined by setColumnWidth(String). The number of columns increases up to the limit set by setMaxColumns(int). The minimum number of columns will be created is set by setMinColumns(int). The component dynamically adjusts the number of columns as the container size changes. When this mode is enabled, Responsive steps are ignored.

      By default, each field is placed on a new row. To organize fields into rows, there are two options:

      1. Use FormLayout.FormRow to explicitly group fields into rows.
      2. Enable the setAutoRows(boolean) property to automatically arrange fields in available columns, wrapping to a new row when necessary. ElementFactory.createBr() elements can be used to force a new row.

      The auto-responsive mode is disabled by default. To enable it for an individual instance, use this method. Alternatively, if you want it to be enabled for all instances by default, enable the following feature flag in src/main/resources/vaadin-featureflags.properties: 

       com.vaadin.experimental.defaultAutoResponsiveFormLayout = true
      Parameters:
      autoResponsive - true to enable auto responsive mode, false to disable

    • setAutoRows

      public void setAutoRows(boolean autoRows)
      Sets whether the component should automatically distribute fields across columns by placing each field in the next available column and wrapping to the next row when the current row is full. ElementFactory.createBr() elements can be used to force a new row.

      The default value is false.

      This setting only applies when setAutoResponsive(boolean) is enabled.

      Parameters:
      autoRows - true to enable auto rows mode, false otherwise

    • isAutoRows

      public boolean isAutoRows()
      Gets whether the component is configured to automatically distribute fields across columns when setAutoResponsive(boolean) is enabled.
      Returns:
      true if auto rows mode is enabled, false otherwise
      See Also:

    • setColumnWidth

      public void setColumnWidth(String columnWidth)
      Sets the width of columns that the component should use when setAutoResponsive(boolean) is enabled. The value must be provided in CSS length units, e.g. 100px.

      When the column width is null, the web component defaults to 12em or uses the value of --vaadin-field-default-width if that CSS custom property is defined.

      This setting only applies when setAutoResponsive(boolean) is enabled.

      Parameters:
      columnWidth - the width of columns or null to use the default

    • setColumnWidth

      public void setColumnWidth(float columnWidth, Unit unit)
      Sets the width of columns that the component should use when setAutoResponsive(boolean) is enabled. The value must be provided with a Unit, e.g. 100 and Unit.PIXELS.

      When the column width is null, the web component defaults to 12em or uses the value of --vaadin-field-default-width if that CSS custom property is defined.

      This setting only applies when setAutoResponsive(boolean) is enabled.

      Parameters:
      columnWidth - the width of columns
      unit - the CSS unit of the width

    • getColumnWidth

      public String getColumnWidth()
      Gets the width of columns that is used when setAutoResponsive(boolean) is enabled.

      When the column width is null, the web component defaults to 12em or uses the value of --vaadin-field-default-width if that CSS custom property is defined.

      Returns:
      the value and CSS unit as a string, or null if not set, in which case the web component uses its default value
      See Also:

    • setMaxColumns

      public void setMaxColumns(int maxColumns)
      Sets the maximum number of columns that the component can create. The component will create columns up to this limit based on the available container width.

      By default, the web component uses a maximum of 10 columns.

      This setting only applies when setAutoResponsive(boolean) is enabled.

      Parameters:
      maxColumns - the maximum number of columns

    • getMaxColumns

      public int getMaxColumns()
      Gets the maximum number of columns that the component can create when #setAutoResponsive(boolean) is enabled.
      Returns:
      the maximum number of columns or 0 if not explicitly set
      See Also:

    • setMinColumns

      public void setMinColumns(int minColumns)
      Sets the minimum number of columns that the component will create.

      By default, the web component uses a minimum of 1 column.

      This setting only applies when setAutoResponsive(boolean) is enabled.

      Parameters:
      minColumns - the minimum number of columns

    • getMinColumns

      public int getMinColumns()
      Gets the minimum number of columns that the component can create when #setAutoResponsive(boolean) is enabled.
      Returns:
      the minimum number of columns or 0 if not explicitly set
      See Also:

    • setExpandColumns

      public void setExpandColumns(boolean expandColumns)
      Sets whether the columns should evenly expand in width to fill any remaining space after all columns have been created.

      The default value is false.

      This setting only applies when setAutoResponsive(boolean) is enabled.

      Parameters:
      expandColumns - true to expand columns, false otherwise

    • isExpandColumns

      public boolean isExpandColumns()
      Gets whether columns are configured to expand to fill remaining space when setAutoResponsive(boolean) is enabled.
      Returns:
      true if columns should expand, false otherwise
      See Also:

    • setExpandFields

      public void setExpandFields(boolean expandFields)
      Sets whether fields should stretch to take up all available space within columns. Fields inside FormLayout.FormItem elements are also included.

      The default value is false.

      This setting only applies when setAutoResponsive(boolean) is enabled.

      Parameters:
      expandFields - true to expand fields, false otherwise

    • isExpandFields

      public boolean isExpandFields()
      Gets whether fields are configured to stretch to take up all available space within columns when setAutoResponsive(boolean) is enabled.
      Returns:
      true if fields should expand, false otherwise
      See Also:

    • setLabelsAside

      public void setLabelsAside(boolean labelsAside)
      Sets whether FormLayout.FormItem should prefer positioning labels beside the fields. If the layout is too narrow to fit a single column with a side label, labels will automatically switch to their default position above the fields until the layout gets wide again.

      This setting only applies when setAutoResponsive(boolean) is enabled.

      To customize the label width and the gap between the label and the field, use the following methods:

      Alternatively, you can use the following CSS custom properties:

      • --vaadin-form-layout-label-width
      • --vaadin-form-layout-label-spacing
      Parameters:
      labelsAside - true to position labels aside, false otherwise

    • isLabelsAside

      public boolean isLabelsAside()
      Gets whether FormLayout.FormItem is configured to prefer positioning labels beside the fields when setAutoResponsive(boolean) is enabled.
      Returns:
      true if labels are positioned aside, false otherwise
      See Also: