Basic Layouts

Vaadin features two basic layout components: Vertical Layout and Horizontal Layout. As their names suggest, they render their contents vertically and horizontally, respectively. Components are shown in the order they are added to either layout.

Vertical Layout

Vertical Layout places components top-to-bottom in a column. By default, it has 100% width and undefined height, meaning its width is constrained by its parent component and its height is determined by the components it contains.

Open in a
new tab
<vaadin-vertical-layout theme="spacing padding">
  <layout-item>Item 1</layout-item>
  <layout-item>Item 2</layout-item>
  <layout-item>Item 3</layout-item>
  <layout-item>Item 4</layout-item>
</vaadin-vertical-layout>

Components in a Vertical Layout can be aligned both vertically and horizontally.

Vertical Alignment

You can position components at the top, middle, or bottom. Alternatively, you can position components by specifying how a layout’s excess space (if any) is distributed between them.

Open in a
new tab
@state()
justifyContent?: string;

render() {
  return html`
    <vaadin-vertical-layout
      theme="spacing padding"
      class="height-5xl"
      style="justify-content: ${this.justifyContent}"
    >
      <layout-item>Item 1</layout-item>
      <layout-item>Item 2</layout-item>
      <layout-item>Item 3</layout-item>
    </vaadin-vertical-layout>
    <vaadin-radio-group
      label="Vertical alignment"
      @value-changed="${(e: RadioGroupValueChangedEvent) =>
        (this.justifyContent = e.detail.value)}"
    >
      <vaadin-radio-button value="flex-start" checked>Start (default)</vaadin-radio-button>
      <vaadin-radio-button value="center">Center</vaadin-radio-button>
      <vaadin-radio-button value="flex-end">End</vaadin-radio-button>
      <vaadin-radio-button value="space-between">Between</vaadin-radio-button>
      <vaadin-radio-button value="space-around">Around</vaadin-radio-button>
      <vaadin-radio-button value="space-evenly">Evenly</vaadin-radio-button>
    </vaadin-radio-group>
  `;
}

Value Description

Value	Description
`START` (default)	Positions items at the top.
`CENTER`	Vertically centers items.
`END`	Positions items at the bottom.
`BETWEEN`	Available space is distributed evenly between items. No space is added before the first item, or after the last.
`AROUND`	Available space is distributed evenly between items. The space before the first item, and after the last, is half of that between items.
`EVENLY`	Available space is distributed evenly between items. The space before the first item, between items and after the last item is the same.

START (default)

Positions items at the top.

CENTER

Vertically centers items.

END

Positions items at the bottom.

BETWEEN

Available space is distributed evenly between items. No space is added before the first item, or after the last.

AROUND

Available space is distributed evenly between items. The space before the first item, and after the last, is half of that between items.

EVENLY

Available space is distributed evenly between items. The space before the first item, between items and after the last item is the same.

Horizontal Alignment

Components in a Vertical Layout can be left-aligned (default), centered, right-aligned or stretched horizontally.

Open in a
new tab
@state()
private alignItems?: string;

render() {
  return html`
    <vaadin-vertical-layout theme="spacing padding" style="align-items: ${this.alignItems}">
      <layout-item>Item 1</layout-item>
      <layout-item>Item 2</layout-item>
      <layout-item>Item 3</layout-item>
    </vaadin-vertical-layout>
    <vaadin-radio-group
      label="Horizontal alignment"
      @value-changed="${(e: RadioGroupValueChangedEvent) => (this.alignItems = e.detail.value)}"
    >
      <vaadin-radio-button value="flex-start" checked>Start (default)</vaadin-radio-button>
      <vaadin-radio-button value="center">Center</vaadin-radio-button>
      <vaadin-radio-button value="flex-end">End</vaadin-radio-button>
      <vaadin-radio-button value="stretch">Stretch</vaadin-radio-button>
    </vaadin-radio-group>
  `;
}

Value Description

Value	Description
`START` (default)	Left-aligns (LTR) or right-aligns (RTL) items
`CENTER`	Horizontally centers items
`END`	Right-aligns (LTR) or left-aligns (RTL) items
`STRETCH`	Stretches items with undefined width horizontally

START (default)

Left-aligns (LTR) or right-aligns (RTL) items

CENTER

Horizontally centers items

END

Right-aligns (LTR) or left-aligns (RTL) items

STRETCH

Stretches items with undefined width horizontally

It is also possible to horizontally align individual components, overriding the alignment set by the parent layout.

Open in a
new tab
@state()
alignLayoutItems?: string;

@state()
alignFirstItem?: string;

render() {
  return html`
    <vaadin-vertical-layout theme="spacing padding" style="align-items: ${this.alignLayoutItems}">
      <layout-item style="align-self: ${this.alignFirstItem}">Item 1</layout-item>
      <layout-item theme="inactive">Item 2</layout-item>
      <layout-item theme="inactive">Item 3</layout-item>
    </vaadin-vertical-layout>
    <vaadin-radio-group
      label="Layout alignment"
      @value-changed="${(e: RadioGroupValueChangedEvent) =>
        (this.alignLayoutItems = e.detail.value)}"
    >
      <vaadin-radio-button value="flex-start" checked>Start (default)</vaadin-radio-button>
      <vaadin-radio-button value="center">Center</vaadin-radio-button>
      <vaadin-radio-button value="flex-end">End</vaadin-radio-button>
      <vaadin-radio-button value="stretch">Stretch</vaadin-radio-button>
    </vaadin-radio-group>
    <vaadin-radio-group
      label="Item 1: alignment"
      @value-changed="${(e: RadioGroupValueChangedEvent) =>
        (this.alignFirstItem = e.detail.value)}"
    >
      <vaadin-radio-button value="auto" checked>Auto (default)</vaadin-radio-button>
      <vaadin-radio-button value="flex-start">Start</vaadin-radio-button>
      <vaadin-radio-button value="center">Center</vaadin-radio-button>
      <vaadin-radio-button value="flex-end">End</vaadin-radio-button>
      <vaadin-radio-button value="stretch">Stretch</vaadin-radio-button>
    </vaadin-radio-group>
  `;
}

Horizontal Layout

Horizontal Layout places components side-by-side in a row. By default, it has undefined width and height, meaning its size is determined by the components it contains.

Open in a
new tab
<vaadin-horizontal-layout theme="spacing padding">
  <layout-item>Item 1</layout-item>
  <layout-item>Item 2</layout-item>
  <layout-item>Item 3</layout-item>
  <layout-item>Item 4</layout-item>
</vaadin-horizontal-layout>

Like Vertical Layout, Horizontal Layout enables both vertical and horizontal alignment of components.

Vertical Alignment

You can position components at the top, middle, or bottom. Items can alternatively be made to stretch vertically or positioned along the layout’s text baseline.

Open in a
new tab
@state()
private alignItems?: string;

render() {
  return html`
    <vaadin-horizontal-layout
      theme="spacing padding"
      class="height-5xl"
      style="align-items: ${this.alignItems}"
    >
      <layout-item>Item 1</layout-item>
      <layout-item>Item 2</layout-item>
      <layout-item>Item 3</layout-item>
    </vaadin-horizontal-layout>
    <vaadin-radio-group
      label="Vertical alignment"
      @value-changed="${(e: RadioGroupValueChangedEvent) => (this.alignItems = e.detail.value)}"
    >
      <vaadin-radio-button value="stretch" checked>Stretch (default)</vaadin-radio-button>
      <vaadin-radio-button value="flex-start">Start</vaadin-radio-button>
      <vaadin-radio-button value="center">Center</vaadin-radio-button>
      <vaadin-radio-button value="flex-end">End</vaadin-radio-button>
      <vaadin-radio-button value="baseline">Baseline</vaadin-radio-button>
    </vaadin-radio-group>
  `;
}

Value Description

Value	Description
`STRETCH` (default)	Stretches items with undefined height horizontally
`START`	Positions items at the top of the layout
`CENTER`	Vertically centers items
`END`	Positions items at the bottom of the layout
`BASELINE`	Position items along the layout’s (text) baseline.

STRETCH (default)

Stretches items with undefined height horizontally

START

Positions items at the top of the layout

CENTER

Vertically centers items

END

Positions items at the bottom of the layout

BASELINE

Position items along the layout’s (text) baseline.

It is also possible to vertically align individual components, overriding the alignment set by the parent layout.

Open in a
new tab
@state()
private alignLayoutItems?: string;

@state()
private alignFirstItem?: string;

render() {
  return html`
    <vaadin-horizontal-layout
      theme="spacing padding"
      class="height-5xl"
      style="align-items: ${this.alignLayoutItems}"
    >
      <layout-item style="align-self: ${this.alignFirstItem}">Item 1</layout-item>
      <layout-item theme="inactive">Item 2</layout-item>
      <layout-item theme="inactive">Item 3</layout-item>
    </vaadin-horizontal-layout>
    <vaadin-radio-group
      label="Vertical alignment"
      @value-changed="${(e: RadioGroupValueChangedEvent) =>
        (this.alignLayoutItems = e.detail.value)}"
    >
      <vaadin-radio-button value="stretch" checked>Stretch (default)</vaadin-radio-button>
      <vaadin-radio-button value="flex-start">Start</vaadin-radio-button>
      <vaadin-radio-button value="center">Center</vaadin-radio-button>
      <vaadin-radio-button value="flex-end">End</vaadin-radio-button>
      <vaadin-radio-button value="baseline">Baseline</vaadin-radio-button>
    </vaadin-radio-group>
    <vaadin-radio-group
      label="Item 1: alignment"
      @value-changed="${(e: RadioGroupValueChangedEvent) =>
        (this.alignFirstItem = e.detail.value)}"
    >
      <vaadin-radio-button value="auto" checked>Auto (default)</vaadin-radio-button>
      <vaadin-radio-button value="stretch">Stretch</vaadin-radio-button>
      <vaadin-radio-button value="flex-start">Start</vaadin-radio-button>
      <vaadin-radio-button value="center">Center</vaadin-radio-button>
      <vaadin-radio-button value="flex-end">End</vaadin-radio-button>
      <vaadin-radio-button value="baseline">Baseline</vaadin-radio-button>
    </vaadin-radio-group>
  `;
}

Horizontal Alignment

Components in a Horizontal Layout can be left-aligned, centered or right-aligned. Alternatively, you can position components by specifying how a layout’s excess space is distributed between them.

Open in a
new tab
@state()
private justifyContent?: string;

render() {
  return html`
    <vaadin-horizontal-layout
      theme="spacing padding"
      style="justify-content: ${this.justifyContent}"
    >
      <layout-item>Item 1</layout-item>
      <layout-item>Item 2</layout-item>
      <layout-item>Item 3</layout-item>
    </vaadin-horizontal-layout>
    <vaadin-radio-group
      label="Horizontal alignment"
      @value-changed="${(e: RadioGroupValueChangedEvent) =>
        (this.justifyContent = e.detail.value)}"
    >
      <vaadin-radio-button value="flex-start" checked>Start (default)</vaadin-radio-button>
      <vaadin-radio-button value="center">Center</vaadin-radio-button>
      <vaadin-radio-button value="flex-end">End</vaadin-radio-button>
      <vaadin-radio-button value="space-between">Between</vaadin-radio-button>
      <vaadin-radio-button value="space-around">Around</vaadin-radio-button>
      <vaadin-radio-button value="space-evenly">Evenly</vaadin-radio-button>
    </vaadin-radio-group>
  `;
}

Value Description

Value	Description
`START` (default)	Left-aligns (LTR) or right-aligns (RTL) items
`END`	Right-aligns (LTR) or left-aligns (RTL) items
`CENTER`	Horizontally centers items
`BETWEEN`	Available space is distributed evenly between items. No space is added before the first item, or after the last.
`AROUND`	Available space is distributed evenly between items. The space before the first item, and after the last, is half of that between items.
`EVENLY`	Available space is distributed evenly between items. The space before the first item, between items and after the last item is the same.

START (default)

Left-aligns (LTR) or right-aligns (RTL) items

END

Right-aligns (LTR) or left-aligns (RTL) items

CENTER

Horizontally centers items

BETWEEN

Available space is distributed evenly between items. No space is added before the first item, or after the last.

AROUND

Available space is distributed evenly between items. The space before the first item, and after the last, is half of that between items.

EVENLY

Available space is distributed evenly between items. The space before the first item, between items and after the last item is the same.

Spacing

Spacing is used to create space between components in the same layout. Spacing can help prevent misclicks and distinguish content areas.

Open in a
new tab
@state()
private theme!: string;

render() {
  return html`
    <vaadin-vertical-layout
      theme="${this.theme} padding"
      class="height-4xl"
      style="align-items: stretch"
    >
      <layout-item>Item 1</layout-item>
      <layout-item>Item 2</layout-item>
      <layout-item>Item 3</layout-item>
    </vaadin-vertical-layout>
    <vaadin-radio-group
      label="Spacing"
      @value-changed="${(e: RadioGroupValueChangedEvent) => (this.theme = e.detail.value)}"
    >
      <vaadin-radio-button value="spacing" checked>Enabled</vaadin-radio-button>
      <vaadin-radio-button value="">Disabled</vaadin-radio-button>
    </vaadin-radio-group>
  `;
}

Warning

CAUTION: Combining spacing and alignment

Vertical Layout’s vertical alignment and Horizontal Layout’s horizontal alignment might not work properly when spacing is enabled. If your layout requires both, consider disabling spacing and handling the alignment using CSS.

Five different spacing theme variants are available:

Open in a
new tab
@state()
private themeVariant!: string;

render() {
  return html`
    <vaadin-vertical-layout
      theme="${this.themeVariant} padding"
      class="height-5xl"
      style="align-items: stretch"
    >
      <layout-item>Item 1</layout-item>
      <layout-item>Item 2</layout-item>
      <layout-item>Item 3</layout-item>
    </vaadin-vertical-layout>
    <vaadin-radio-group
      label="Spacing variant"
      @value-changed="${(e: RadioGroupValueChangedEvent) => (this.themeVariant = e.detail.value)}"
    >
      <vaadin-radio-button value="spacing-xs" checked>spacing-xs</vaadin-radio-button>
      <vaadin-radio-button value="spacing-s" checked>spacing-s</vaadin-radio-button>
      <vaadin-radio-button value="spacing" checked>spacing</vaadin-radio-button>
      <vaadin-radio-button value="spacing-l" checked>spacing-l</vaadin-radio-button>
      <vaadin-radio-button value="spacing-xl" checked>spacing-xl</vaadin-radio-button>
    </vaadin-radio-group>
  `;
}

Theme variant Usage recommendations

Theme variant	Usage recommendations
`spacing-xs`	Extra small space between items
`spacing-s`	Small space between items
`spacing`	Medium space between items
`spacing-l`	Large space between items
`spacing-xl`	Extra large space between items

spacing-xs

Extra small space between items

spacing-s

Small space between items

spacing

Medium space between items

spacing-l

Large space between items

spacing-xl

Extra large space between items

Padding

Padding is the space between a layout’s outer border and its content. Padding can help distinguish a layout’s content from its surroundings. Padding is applied using the padding theme variant.

Open in a
new tab
@state()
private theme!: string;

render() {
  return html`
    <vaadin-vertical-layout
      theme="${this.theme} spacing"
      class="height-4xl"
      style="align-items: stretch"
    >
      <layout-item>Item 1</layout-item>
      <layout-item>Item 2</layout-item>
      <layout-item>Item 3</layout-item>
    </vaadin-vertical-layout>
    <vaadin-radio-group
      label="Padding"
      @value-changed="${(e: RadioGroupValueChangedEvent) => (this.theme = e.detail.value)}"
    >
      <vaadin-radio-button value="padding" checked>Enabled </vaadin-radio-button>
      <vaadin-radio-button value="">Disabled</vaadin-radio-button>
    </vaadin-radio-group>
  `;
}

Margin

Use margin to create space around a layout.

Open in a
new tab
@state()
private theme!: string;

render() {
  return html`
    <div class="container">
      <vaadin-vertical-layout theme="${this.theme} spacing padding" style="align-items: stretch">
        <layout-item>Item 1</layout-item>
        <layout-item>Item 2</layout-item>
        <layout-item>Item 3</layout-item>
      </vaadin-vertical-layout>
    </div>
    <vaadin-radio-group
      label="Margin"
      @value-changed="${(e: RadioGroupValueChangedEvent) => (this.theme = e.detail.value)}"
    >
      <vaadin-radio-button value="margin" checked>Enabled</vaadin-radio-button>
      <vaadin-radio-button value="">Disabled</vaadin-radio-button>
    </vaadin-radio-group>
  `;
}

Expanding Items

Components can be made to expand and take up any excess space a layout may have.

Open in a
new tab
@state()
private size!: string;

render() {
  return html`
    <vaadin-horizontal-layout theme="padding spacing">
      <layout-item style="flex-grow: ${this.size}">Item 1</layout-item>
      <layout-item>Item 2</layout-item>
      <layout-item>Item 3</layout-item>
    </vaadin-horizontal-layout>
    <vaadin-radio-group
      label="Item sizing"
      @value-changed="${(e: RadioGroupValueChangedEvent) => (this.size = e.detail.value)}"
    >
      <vaadin-radio-button value="0" checked>Default size</vaadin-radio-button>
      <vaadin-radio-button value="1">Expand</vaadin-radio-button>
    </vaadin-radio-group>
  `;
}

When multiple components expand, they do so relative to each other. For example, two items with expand ratios of 2 and 1, will result in the first item taking up twice as much of the available space as the second item.

My Design System

My Design System

Basic Layouts

Vertical Layout

Vertical Alignment

Horizontal Alignment

Horizontal Layout

Vertical Alignment

Horizontal Alignment

Spacing

Padding

Margin

Expanding Items