Docs

Docs

Horizontal Layout

Source: TypeScript / Java
Horizontal Layout places components side-by-side in a row.

Horizontal Layout places components side-by-side in a row. By default, it defines its width and height automatically, determined by the components it contains (i.e., it “hugs” the content).

See Vertical Layout for placing components top-to-bottom.

Open in a
new tab
HorizontalLayout layout = new HorizontalLayout();
layout.setPadding(true);

Div item1 = new Div("Item 1");
item1.setClassName("example-item");

Div item2 = new Div("Item 2");
item2.setClassName("example-item");

Div item3 = new Div("Item 3");
item3.setClassName("example-item");

layout.add(item1, item2, item3);

Components in a Horizontal Layout can be aligned horizontally, as you’d expect, but also vertically.

Vertical Alignment

You can position components at the top, middle, or bottom. You can also stretch items or position them along the text baseline in the layout.

Open in a
new tab
HorizontalLayout layout = new HorizontalLayout();
layout.setPadding(true);
layout.setAlignItems(FlexComponent.Alignment.CENTER);

Div item1 = new Div("Item 1");
item1.setClassName("example-item");

Div item2 = new Div("Item 2");
item2.setClassName("example-item");

Div item3 = new Div("Item 3");
item3.setClassName("example-item");

layout.add(item1, item2, item3);
Value Description

STRETCH (default)

Vertically stretches items that have undefined height.

START

Positions items at the top of the layout.

CENTER

Centers items, vertically.

END

Positions items at the bottom of the layout.

BASELINE

Positions items along the layout’s text baseline.

It’s also possible to set a different vertical alignment for individual items by overriding the general alignment setting of the layout.

Open in a
new tab
HorizontalLayout layout = new HorizontalLayout();
layout.setPadding(true);
layout.setAlignItems(FlexComponent.Alignment.STRETCH);

Div item1 = new Div("Item 1");
item1.setClassName("example-item");
layout.add(item1);
layout.setAlignSelf(FlexComponent.Alignment.START, item1);

Div item2 = new Div("Item 2");
item2.setClassName("example-item");
layout.add(item2);

Div item3 = new Div("Item 3");
item3.setClassName("example-item");
layout.add(item3);
layout.setAlignSelf(FlexComponent.Alignment.END, item3);

Horizontal Alignment

Components in a Horizontal Layout can be left-aligned, centered or right-aligned. You can also position components by specifying how the excess space in a layout is distributed among them.

Open in a
new tab
HorizontalLayout layout = new HorizontalLayout();
layout.setPadding(true);
layout.setJustifyContentMode(FlexComponent.JustifyContentMode.CENTER);

Div item1 = new Div("Item 1");
item1.setClassName("example-item");

Div item2 = new Div("Item 2");
item2.setClassName("example-item");

Div item3 = new Div("Item 3");
item3.setClassName("example-item");

layout.add(item1, item2, item3);
Value Description

START (default)

Left-aligns for left-to-right language items. For right-to-left languages, right-aligns items.

CENTER

Centers items, horizontally.

END

Right-aligns for left-to-right language items. For right-to-left languages, left-aligns 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 around 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 among components in the same layout. Spacing can help prevent misclicks and distinguish content areas.

Open in a
new tab
// HorizontalLayout has spacing enabled by default, use setSpacing to
// disable it
HorizontalLayout layoutWithoutSpacing = new HorizontalLayout();
layoutWithoutSpacing.setSpacing(false);

Five different spacing theme variants are available:

Open in a
new tab
@state()
private themeVariant = 'spacing-xl';

protected override render() {
  return html`
    <vaadin-horizontal-layout theme="${this.themeVariant} padding" style="align-items: stretch">
      <div class="example-item">Item 1</div>
      <div class="example-item">Item 2</div>
      <div class="example-item">Item 3</div>
    </vaadin-horizontal-layout>
    <vaadin-radio-group
      label="Spacing variant"
      .value="${this.themeVariant}"
      @value-changed="${(event: RadioGroupValueChangedEvent) => {
        this.themeVariant = event.detail.value;
      }}"
    >
      <vaadin-radio-button value="spacing-xs" label="spacing-xs"></vaadin-radio-button>
      <vaadin-radio-button value="spacing-s" label="spacing-s"></vaadin-radio-button>
      <vaadin-radio-button value="spacing" label="spacing"></vaadin-radio-button>
      <vaadin-radio-button value="spacing-l" label="spacing-l"></vaadin-radio-button>
      <vaadin-radio-button value="spacing-xl" label="spacing-xl"></vaadin-radio-button>
    </vaadin-radio-group>
  `;
}
Theme Variant Usage Recommendation

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.

 
HorizontalLayout layout = new HorizontalLayout();
layout.setSpacing(false);
layout.getThemeList().add("spacing-xs");

Padding

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

Open in a
new tab
HorizontalLayout layoutWithPadding = new HorizontalLayout();
layoutWithPadding.setPadding(true);

Margin

Use margin to create space around a layout.

Open in a
new tab
HorizontalLayout layoutWithMargin = new HorizontalLayout();
layoutWithMargin.setMargin(true);

Wrapping

By default, components in a layout either shrink or overflow when there isn’t enough horizontal space. Enable wrapping to allow components to flow onto a new line when space runs out, preventing overflow.

Open in a
new tab
HorizontalLayout layoutWithWrap = new HorizontalLayout();
layoutWithWrap.setWrap(true);

Expanding Items

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

Open in a
new tab
Div item1 = new Div("Item 1");
item1.setClassName("example-item");
HorizontalLayout layout = new HorizontalLayout();
layout.setFlexGrow(1, item1);

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

Troubleshooting

Component is Smaller than its Specified Size

In some situations, a component with a specific, fixed size is rendered smaller than that size (and its size may vary depending on the size of the UI).

This is usually caused by the component being placed in the same Horizontal or Vertical Layout as another component with 100% (or “full”) size along the same axis.

The reason for this behavior is a combination of two aspects of Horizontal Layout and Vertical Layout:

  • 100% width or height actually means the full width or height of the layout, rather than whatever space is available after any fixed-size items.

  • By default, children of these layouts are allowed to shrink below their specified size. While this allows full-size items to shrink below 100% to make room for other items, it also makes fixed-size items shrink a bit.

There are three main ways to solve this issue:

Prevent the fixed-size element from shrinking

By setting the flex-shrink value of the fixed size component to 0, it is prevented from shrinking below that size.

HorizontalLayout layout = new HorizontalLayout(fixedSizeComponent, fullSizeComponent);
fixedSizeComponent.setWidth("200px");
fullSizeComponent.setWidthFull();

layout.setFlexShrink(fixedSizeComponent, 0);
// or
fixedSizeComponent.getStyle().setFlexShrink("0");

Use Flex-Grow Instead of 100% Size

Instead of setting a 100% (or “full”) size, you can make a component take all available space by setting its flex-grow value to 1.

HorizontalLayout layout = new HorizontalLayout(fixedSizeComponent, fullSizeComponent);
fixedSizeComponent.setWidth("200px");

layout.setFlexGrow(fullSizeComponent, 1);
// or
fullSizeComponent.getStyle().setFlexGrow("1");

Enable Layout Improvements (Flow only, experimental)

By enabling the layoutComponentImprovements feature flag, the Flow APIs setWidthFull, setHeightFull and setSizeFull are rewired to automatically apply flex:1 to the component. This prevents fixed-size components from shrinking and makes the full-size component take up the remaining space in the layout.

Component Overflows its Specified Size

This is most commonly noticed on scroll containers like Scroller and TabSheet, or elements that have been scroll-enabled through CSS, but it can occur in other situations as well. The problem often causes extra undesired scrollbars to appear.

This is caused by the default minimum size of a layout item to be equal to the size of its contents.

There are three main ways to solve this issue:

Set an Appropriate Minimum Size

Set the minimum size to 0 or any other specific size.

overFlowingComponent.setMinWidth("0");

Prevent Overflow

You can prevent the component from overflowing by setting the CSS overflow property to hidden. Be aware that this will also clip outlines and box-shadows, such as those used for focus rings.

overFlowingComponent.getStyle().setOverflow(Overflow.HIDDEN);

Enable Layout Improvements (Flow only, experimental)

By enabling the layoutComponentImprovements feature flag, the Flow APIs setWidthFull, setHeightFull and setSizeFull are rewired to also set the minimum size of nested Horizontal and Vertical Layouts to 0, allowing them to shrink below the size of their contents.

61c42eee-d39a-11ed-afa1-0242ac120002