FormLayout

Description #

<vaadin-form-layout> is a Web Component providing configurable responsive layout for form elements.

<vaadin-form-layout>

  <vaadin-form-item>
    <label slot="label">First Name</label>
    <input class="full-width" value="Jane">
  </vaadin-form-item>

  <vaadin-form-item>
    <label slot="label">Last Name</label>
    <input class="full-width" value="Doe">
  </vaadin-form-item>

  <vaadin-form-item>
    <label slot="label">Email</label>
    <input class="full-width" value="jane.doe@example.com">
  </vaadin-form-item>

</vaadin-form-layout>

It supports any child elements as layout items.

By default, it makes a layout of two columns if the element width is equal or wider than 40em, and a single column layout otherwise.

The number of columns and the responsive behavior are customizable with the responsiveSteps property.

Spanning Items on Multiple Columns #

You can use colspan or data-colspan attribute on the items. In the example below, the first text field spans on two columns:

<vaadin-form-layout>

  <vaadin-form-item colspan="2">
    <label slot="label">Address</label>
    <input class="full-width">
  </vaadin-form-item>

  <vaadin-form-item>
    <label slot="label">First Name</label>
    <input class="full-width" value="Jane">
  </vaadin-form-item>

  <vaadin-form-item>
    <label slot="label">Last Name</label>
    <input class="full-width" value="Doe">
  </vaadin-form-item>

</vaadin-form-layout>

Explicit New Row #

Use the <br> line break element to wrap the items on a new row:

<vaadin-form-layout>

  <vaadin-form-item>
    <label slot="label">Email</label>
    <input class="full-width">
  </vaadin-form-item>

  <br>

  <vaadin-form-item>
    <label slot="label">Confirm Email</label>
    <input class="full-width">
  </vaadin-form-item>

</vaadin-form-layout>

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.

The columnWidth and maxColumns properties define the width of each column and the maximum number of columns that the component can create. By default, the component creates up to 10 columns, each with a width of 12em or the value of the --vaadin-field-default-width CSS custom property, if defined.

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

<vaadin-form-layout auto-responsive>
  <vaadin-text-field label="First Name"></vaadin-text-field>
  <vaadin-text-field label="Last Name"></vaadin-text-field>
  <vaadin-text-area label="Address" colspan="2"></vaadin-text-area>
</vaadin-form-layout>

You can also enable it for all instances by enabling the following feature flag before <vaadin-form-layout> elements are added to the DOM:

window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout = true;

Organizing Fields into Rows #

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

1. Manually wrap fields into <vaadin-form-row> elements.

2. Enable the autoRows property to let Form Layout automatically arrange fields in available columns, wrapping to a new row when necessary. <br> elements can be used to force a new row.

Here is an example of using <vaadin-form-row>:

<vaadin-form-layout auto-responsive>
  <vaadin-form-row>
    <vaadin-text-field label="First Name"></vaadin-text-field>
    <vaadin-text-field label="Last Name"></vaadin-text-field>
  </vaadin-form-row>
  <vaadin-form-row>
    <vaadin-text-area label="Address" colspan="2"></vaadin-text-area>
  </vaadin-form-row>
</vaadin-form-layout>

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 <vaadin-form-item> element and define its labels on the wrapper. Then, you can enable the labelsAside property:

<vaadin-form-layout auto-responsive labels-aside>
  <vaadin-form-row>
    <vaadin-form-item>
      <label slot="label">First Name</label>
      <vaadin-text-field></vaadin-text-field>
   </vaadin-form-item>
   <vaadin-form-item>
     <label slot="label">Last Name</label>
      <vaadin-text-field></vaadin-text-field>
    </vaadin-form-item>
  </vaadin-form-row>
  <vaadin-form-row>
    <vaadin-form-item colspan="2">
      <label slot="label">Address</label>
      <vaadin-text-area></vaadin-text-area>
    </vaadin-form-item>
  </vaadin-form-row>
</vaadin-form-layout>

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

CSS Properties Reference #

The following custom CSS properties are available on the <vaadin-form-layout> element:

Custom CSS property	Description	Default
--vaadin-form-layout-column-spacing	Length of the spacing between columns	2em
--vaadin-form-layout-row-spacing	Length of the spacing between rows	1em
--vaadin-form-layout-label-width	Width of the label when labels are displayed aside	8em
--vaadin-form-layout-label-spacing	Length of the spacing between the label and the input when labels are displayed aside	1em

Properties #

autoResponsive #

Type: boolean

When set to true, the component automatically creates and adjusts columns based on the container's width. Columns have a fixed width defined by columnWidth and their number increases up to the limit set by maxColumns. The component dynamically adjusts the number of columns as the container size changes. When this mode is enabled, responsiveSteps are ignored.

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

1. Use <vaadin-form-row> to explicitly group fields into rows.

2. Enable the autoRows property to automatically arrange fields in available columns, wrapping to a new row when necessary. <br> 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 property. Alternatively, if you want it to be enabled for all instances by default, enable the defaultAutoResponsiveFormLayout feature flag before <vaadin-form-layout> elements are added to the DOM:

window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout = true;

autoRows #

Type: boolean

When enabled with autoResponsive, distributes fields across columns by placing each field in the next available column and wrapping to the next row when the current row is full. <br> elements can be used to force a new row.

The default value is false.

columnWidth #

Type: string

When autoResponsive is enabled, defines the width of each column. The value must be defined in CSS length units, e.g. 100px.

If the column width isn't explicitly set, it defaults to 12em or --vaadin-field-default-width if that CSS property is defined.

expandColumns #

Type: boolean

When autoResponsive is enabled, specifies whether the columns should expand in width to evenly fill any remaining space after all columns have been created.

The default value is false.

expandFields #

Type: boolean

When autoResponsive is enabled, specifies whether fields should stretch to take up all available space within columns. This setting also applies to fields inside <vaadin-form-item> elements.

The default value is false.

labelsAside #

Type: boolean

When enabled with autoResponsive, <vaadin-form-item> prefers positioning labels beside the fields. If the layout is too narrow to fit a single column with a side label, the component will automatically switch labels to their default position above the fields.

The default value is false.

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

• --vaadin-form-layout-label-width
• --vaadin-form-layout-label-spacing

maxColumns #

Type: number

When autoResponsive is enabled, defines the maximum number of columns that the layout can create. The layout will create columns up to this limit based on the available container width.

The default value is 10.

minColumns #

Type: number

When autoResponsive is enabled, defines the minimum number of columns that the layout can create. The layout will create columns at least up to this limit.

The default value is 1.

responsiveSteps #

Type: FormLayoutResponsiveStep[]

Allows specifying a responsive behavior with the number of columns and the label position depending on the layout width.

Format: array of objects, each object defines one responsive step with minWidth CSS length, columns number, and optional labelsPosition string of "aside" or "top". At least one item is required.

NOTE: Responsive steps are ignored in auto-responsive mode, which may be enabled explicitly via the autoResponsive property or implicitly if the following feature flag is set:

window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout = true

Examples #

formLayout.responsiveSteps = [{columns: 1}];
// The layout is always a single column, labels aside.

formLayout.responsiveSteps = [
  {minWidth: 0, columns: 1},
  {minWidth: '40em', columns: 2}
];
// Sets two responsive steps:
// 1. When the layout width is < 40em, one column, labels aside.
// 2. Width >= 40em, two columns, labels aside.

formLayout.responsiveSteps = [
  {minWidth: 0, columns: 1, labelsPosition: 'top'},
  {minWidth: '20em', columns: 1},
  {minWidth: '40em', columns: 2}
];
// Default value. Three responsive steps:
// 1. Width < 20em, one column, labels on top.
// 2. 20em <= width < 40em, one column, labels aside.
// 3. Width >= 40em, two columns, labels aside.

See also: FormLayoutResponsiveStep

slotStyles #

Type: string[]

Types #

FormLayoutLabelsPosition #

export type FormLayoutLabelsPosition = 'aside' | 'top';

FormLayoutResponsiveStep #

export type FormLayoutResponsiveStep = {
  minWidth?: string | 0;
  columns: number;
  labelsPosition?: FormLayoutLabelsPosition;
};