Split Layout

Orientation
Splitter Position
Theme Variants
Best Practices

Split Layout is a component with two content areas and a draggable split handle between them.

Source code

split-layout-basic.tsimport { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/split-layout';
import { applyTheme } from 'Frontend/generated/theme';
import './master-content';
import './detail-content';

@customElement('split-layout-basic')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-split-layout style="max-height: 280px;">
        <master-content></master-content>
        <detail-content></detail-content>
      </vaadin-split-layout>
      <!-- end::snippet[] -->
    `;
  }
}
SplitLayoutBasic.javapackage com.vaadin.demo.component.splitlayout;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.splitlayout.SplitLayout;
import com.vaadin.flow.router.Route;

@Route("split-layout-basic")
public class SplitLayoutBasic extends Div {

    public SplitLayoutBasic() {
        // tag::snippet[]
        MasterContent master = new MasterContent();
        DetailContent detail = new DetailContent();

        SplitLayout splitLayout = new SplitLayout(master, detail);
        // end::snippet[]

        splitLayout.setMaxHeight("280px");
        add(splitLayout);
    }

}

Orientation

The default orientation is horizontal, placing the content areas side by side. The orientation can also be vertical.

Orientation should be set based on the content and the screen size. The user can also be allowed to choose which orientation they want to use.

Open in a
new tab

Source code

split-layout-orientation.tsimport { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/split-layout';
import { applyTheme } from 'Frontend/generated/theme';
import './master-content';
import './detail-content';

@customElement('split-layout-orientation')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-split-layout style="max-height: 350px;" orientation="vertical">
        <master-content></master-content>
        <detail-content></detail-content>
      </vaadin-split-layout>
      <!-- end::snippet[] -->
    `;
  }
}
SplitLayoutOrientation.javapackage com.vaadin.demo.component.splitlayout;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.splitlayout.SplitLayout;
import com.vaadin.flow.router.Route;

@Route("split-layout-orientation")
public class SplitLayoutOrientation extends Div {

    public SplitLayoutOrientation() {
        // tag::snippet[]
        MasterContent master = new MasterContent();
        DetailContent detail = new DetailContent();

        SplitLayout splitLayout = new SplitLayout(master, detail);
        splitLayout.setOrientation(SplitLayout.Orientation.VERTICAL);
        // end::snippet[]

        splitLayout.setMaxHeight("350px");
        add(splitLayout);
    }

}

Splitter Position

The initial splitter position is determined by the default size of the two content area components. Their height and width affect the position when using a vertical and horizontal orientation, respectively.

The initial split position can also be explicitly set using a percentage value. When using vertical orientation, the split layout must have an explicit height for this to work. This can be either an absolute or a percentage value. When using a percentage value, ensure that ancestors have an explicit height as well.

Open in a
new tab

Source code

split-layout-initial-splitter-position.tsimport { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/split-layout';
import { applyTheme } from 'Frontend/generated/theme';
import './master-content';
import './detail-content';

@customElement('split-layout-initial-splitter-position')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-split-layout style="max-height: 280px;">
        <master-content style="width: 70%;"></master-content>
        <detail-content style="width: 30%;"></detail-content>
      </vaadin-split-layout>
      <!-- end::snippet[] -->
    `;
  }
}
SplitLayoutInitialSplitterPosition.javapackage com.vaadin.demo.component.splitlayout;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.splitlayout.SplitLayout;
import com.vaadin.flow.router.Route;

@Route("split-layout-initial-splitter-position")
public class SplitLayoutInitialSplitterPosition extends Div {

    public SplitLayoutInitialSplitterPosition() {
        // tag::snippet[]
        MasterContent master = new MasterContent();
        DetailContent detail = new DetailContent();

        SplitLayout splitLayout = new SplitLayout(master, detail);
        // Sets the width for the first child to 70%, giving
        // the second child the remaining width of 30%
        splitLayout.setSplitterPosition(70);
        // end::snippet[]

        splitLayout.setMaxHeight("280px");
        add(splitLayout);
    }

}

The splitter respects the minimum and maximum size of the content area components.

Open in a
new tab

Source code

split-layout-min-max-size.tsimport { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/split-layout';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('split-layout-min-max-size')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-split-layout style="max-height: 280px;">
        <master-content style="min-width: 200px; max-width: 400px;"></master-content>
        <detail-content></detail-content>
      </vaadin-split-layout>
      <!-- end::snippet[] -->
    `;
  }
}
SplitLayoutMinMaxSize.javapackage com.vaadin.demo.component.splitlayout;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.splitlayout.SplitLayout;
import com.vaadin.flow.router.Route;

@Route("split-layout-min-max-size")
public class SplitLayoutMinMaxSize extends Div {

    public SplitLayoutMinMaxSize() {
        // tag::snippet[]
        MasterContent master = new MasterContent();
        master.setMinWidth("200px");
        master.setMaxWidth("400px");

        DetailContent detail = new DetailContent();

        SplitLayout splitLayout = new SplitLayout(master, detail);
        // end::snippet[]

        splitLayout.setMaxHeight("280px");
        add(splitLayout);
    }

}

The split can be adjusted programmatically, for example by using a Button. This is useful when the user wants to toggle between certain positions.

Open in a
new tab

Source code

split-layout-toggle.tsimport { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/button';
import '@vaadin/icon';
import '@vaadin/icons';
import '@vaadin/split-layout';
import { applyTheme } from 'Frontend/generated/theme';
import './master-content';
import './detail-content';

@customElement('split-layout-toggle')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  // tag::snippet[]
  @state()
  private sidebarCollapsed = false;

  protected override render() {
    const sidebarWidthPercentage = this.sidebarCollapsed ? 13 : 40;

    return html`
      <vaadin-split-layout style="max-height: 280px;">
        <div style="overflow: hidden; width: ${sidebarWidthPercentage}%">
          <vaadin-button
            theme="icon tertiary"
            aria-label="Expand/collapse sidebar"
            @click="${this.toggleSidebar}"
            style="float: right;"
          >
            <vaadin-icon
              icon="${this.sidebarCollapsed ? 'vaadin:arrow-right' : 'vaadin:arrow-left'}"
            ></vaadin-icon>
          </vaadin-button>
          <master-content></master-content>
        </div>
        <detail-content style="width: ${100 - sidebarWidthPercentage}%"></detail-content>
      </vaadin-split-layout>
    `;
  }

  toggleSidebar() {
    this.sidebarCollapsed = !this.sidebarCollapsed;
  }
  // end::snippet[]
}
SplitLayoutToggle.javapackage com.vaadin.demo.component.splitlayout;

import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.button.ButtonVariant;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.icon.Icon;
import com.vaadin.flow.component.icon.VaadinIcon;
import com.vaadin.flow.component.splitlayout.SplitLayout;
import com.vaadin.flow.router.Route;

@Route("split-layout-toggle")
public class SplitLayoutToggle extends Div {
    private boolean sidebarCollapsed;
    private final Button button;
    private final Icon leftArrowIcon;
    private final Icon rightArrowIcon;
    private final SplitLayout splitLayout;

    public SplitLayoutToggle() {
        // tag::snippet[]
        button = new Button();
        leftArrowIcon = VaadinIcon.ARROW_LEFT.create();
        rightArrowIcon = VaadinIcon.ARROW_RIGHT.create();
        Div masterContainer = new Div();
        DetailContent detailContent = new DetailContent();
        MasterContent masterContent = new MasterContent();

        sidebarCollapsed = false;

        button.addClickListener(event -> {
            sidebarCollapsed = !sidebarCollapsed;
            updateSidebar();
        });
        button.getElement().setAttribute("aria-label",
                "Expand/collapse sidebar");
        button.addThemeVariants(ButtonVariant.LUMO_TERTIARY);
        button.getStyle().set("float", "right");

        masterContainer.add(button, masterContent);
        masterContainer.getStyle().set("overflow", "hidden");

        splitLayout = new SplitLayout(masterContainer, detailContent);

        updateSidebar();
        // end::snippet[]

        splitLayout.setMaxHeight("280px");
        add(splitLayout);
    }

    private void updateSidebar() {
        button.setIcon(sidebarCollapsed ? rightArrowIcon : leftArrowIcon);
        splitLayout.setSplitterPosition(sidebarCollapsed ? 13 : 40);
    }

}

Theme Variants

Split Layout has two theme variants: small and minimal.

Open in a
new tab

Source code

split-layout-theme-small.tsimport { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/split-layout';
import { applyTheme } from 'Frontend/generated/theme';
import './master-content';
import './detail-content';

@customElement('split-layout-theme-small')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-split-layout style="max-height: 280px;" theme="small">
        <master-content></master-content>
        <detail-content></detail-content>
      </vaadin-split-layout>
      <!-- end::snippet[] -->
    `;
  }
}
SplitLayoutThemeVariants.javapackage com.vaadin.demo.component.splitlayout;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.splitlayout.SplitLayout;
import com.vaadin.flow.component.splitlayout.SplitLayoutVariant;
import com.vaadin.flow.router.Route;

@Route("split-layout-theme-variants")
public class SplitLayoutThemeVariants extends Div {

    public SplitLayoutThemeVariants() {
        // tag::snippet[]
        MasterContent master = new MasterContent();
        DetailContent detail = new DetailContent();

        SplitLayout splitLayout = new SplitLayout(master, detail);
        splitLayout.addThemeVariants(SplitLayoutVariant.LUMO_SMALL);
        // end::snippet[]

        splitLayout.setMaxHeight("280px");
        add(splitLayout);
    }

}

The small theme variant makes the divider smaller. The minimal theme variant hides the visual divider. Both variants only show the split handle on hover and aren’t ideal for touch devices.

Open in a
new tab

Source code

split-layout-theme-minimal.tsimport { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/split-layout';
import { applyTheme } from 'Frontend/generated/theme';
import './master-content';
import './detail-content';

@customElement('split-layout-theme-minimal')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-split-layout style="max-height: 280px;" theme="minimal">
        <master-content></master-content>
        <detail-content></detail-content>
      </vaadin-split-layout>
      <!-- end::snippet[] -->
    `;
  }
}
SplitLayoutMinimalThemeVariants.javapackage com.vaadin.demo.component.splitlayout;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.splitlayout.SplitLayout;
import com.vaadin.flow.component.splitlayout.SplitLayoutVariant;
import com.vaadin.flow.router.Route;

@Route("split-layout-minimal-theme-variants")
public class SplitLayoutMinimalThemeVariants extends Div {

    public SplitLayoutMinimalThemeVariants() {
        // tag::snippet[]
        MasterContent master = new MasterContent();
        DetailContent detail = new DetailContent();

        SplitLayout splitLayout = new SplitLayout(master, detail);
        splitLayout.addThemeVariants(SplitLayoutVariant.LUMO_MINIMAL);
        // end::snippet[]

        splitLayout.setMaxHeight("280px");
        add(splitLayout);
    }

}

When using the minimal theme variant, it’s recommended to somehow suggest the split between the two sides, for example by styling one side as a layer on top of the other.

While these variants reduce visual clutter, they make it less obvious to the user that the content is resizable.

Best Practices

Don’t use Split Layout when either content area has, or should have, a fixed size.
Split Layouts can be difficult to use in responsive applications, due to the splitter position being percentage-based, so that the content scales with the viewport.
Use Split Layout to give the user the ability to adjust the layout. However, if only specific positions, such as collapsed and expanded, are useful to the user, use a toggle button instead. Non-adjustable layouts should use Ordered Layouts or Flex Layout.

10387B24-0DDF-4FC8-B5F9-B6319633D354

Documentation

Documentation

Split Layout

Orientation

Splitter Position

Theme Variants

Best Practices