---
title: FormLayout
description: FormLayout
element: vaadin-form-layout
---

## Description

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

```html
<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:

```html
<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:

```html
<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`](/elements/vaadin-form-layout#columnwidth) and
[`maxColumns`](/elements/vaadin-form-layout#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:

```html
<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:

```js
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/vaadin-form-row) elements.

2. Enable the [`autoRows`](/elements/vaadin-form-layout#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>`:

```html
<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`](/elements/vaadin-form-layout#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`](/elements/vaadin-form-layout#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`](/elements/vaadin-form-layout#labelsaside)
property:

```html
<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 for styling:

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:

```js
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:

```js
window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout = true
```

#### Examples

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

```javascript
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.
```

```javascript
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](#formlayoutresponsivestep)

## Types

### FormLayoutLabelsPosition

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

### FormLayoutResponsiveStep

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