Split Layout

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

Orientation
Splitter Position
Accessibility
Best Practices

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

Source code

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);
    }

}
split-layout-basic.tsximport React from 'react';
import { SplitLayout } from '@vaadin/react-components/SplitLayout';
import DetailContent from './detail-content';
import MasterContent from './master-content';

function Example() {
  return (
    // tag::snippet[]
    <SplitLayout style={{ maxHeight: '280px' }}>
      <MasterContent />
      <DetailContent />
    </SplitLayout>
    // end::snippet[]
  );
}

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

@customElement('split-layout-basic')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    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[] -->
    `;
  }
}

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

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);
    }

}
split-layout-orientation.tsximport React from 'react';
import { SplitLayout } from '@vaadin/react-components/SplitLayout.js';
import DetailContent from './detail-content';
import MasterContent from './master-content';

function Example() {
  return (
    // tag::snippet[]
    <SplitLayout style={{ maxHeight: '350px' }} orientation="vertical">
      <MasterContent />
      <DetailContent />
    </SplitLayout>
    // end::snippet[]
  );
}

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

@customElement('split-layout-orientation')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    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[] -->
    `;
  }
}

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

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);
    }

}
split-layout-initial-splitter-position.tsximport React from 'react';
import { SplitLayout } from '@vaadin/react-components/SplitLayout.js';
import DetailContent from './detail-content';
import MasterContent from './master-content';

function Example() {
  return (
    // tag::snippet[]
    <SplitLayout style={{ maxHeight: '280px' }}>
      <MasterContent style={{ width: '70%' }} />
      <DetailContent style={{ width: '30%' }} />
    </SplitLayout>
    // end::snippet[]
  );
}

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

@customElement('split-layout-initial-splitter-position')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    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[] -->
    `;
  }
}

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

Open in a
new tab

Source code

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);
    }

}
split-layout-min-max-size.tsximport React from 'react';
import { SplitLayout } from '@vaadin/react-components/SplitLayout.js';
import DetailContent from './detail-content';
import MasterContent from './master-content';

function Example() {
  return (
    // tag::snippet[]
    <SplitLayout style={{ maxHeight: '280px' }}>
      <MasterContent style={{ minWidth: '200px', maxWidth: '400px' }} />
      <DetailContent />
    </SplitLayout>
    // end::snippet[]
  );
}

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

@customElement('split-layout-min-max-size')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    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[] -->
    `;
  }
}

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

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();
        masterContent.getStyle().set("clear", "right");

        sidebarCollapsed = false;

        button.addClickListener(event -> {
            sidebarCollapsed = !sidebarCollapsed;
            updateSidebar();
        });
        button.setAriaLabel("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);
    }

}
split-layout-toggle.tsximport '@vaadin/icons';
import React from 'react';
import { useSignal } from '@vaadin/hilla-react-signals';
import { Button } from '@vaadin/react-components/Button.js';
import { Icon } from '@vaadin/react-components/Icon.js';
import { SplitLayout } from '@vaadin/react-components/SplitLayout.js';
import DetailContent from './detail-content';
import MasterContent from './master-content';

function Example() {
  // tag::snippet[]
  const sidebarCollapsed = useSignal(false);

  const toggleSidebar = () => {
    sidebarCollapsed.value = !sidebarCollapsed.value;
  };

  const sidebarWidthPercentage = sidebarCollapsed.value ? 13 : 40;

  return (
    <SplitLayout style={{ maxHeight: '280px' }}>
      <div
        style={{
          overflow: 'hidden',
          width: `${sidebarWidthPercentage}%`,
          display: 'flex',
          flexDirection: 'column',
        }}
      >
        <Button
          theme="icon tertiary"
          aria-label="Expand/collapse sidebar"
          onClick={toggleSidebar}
          style={{ alignSelf: 'flex-end' }}
        >
          <Icon icon={sidebarCollapsed.value ? 'vaadin:arrow-right' : 'vaadin:arrow-left'} />
        </Button>
        <MasterContent style={{ clear: 'right' }} />
      </div>

      <div style={{ width: `${100 - sidebarWidthPercentage}%` }}>
        <DetailContent />
      </div>
    </SplitLayout>
  );
  // end::snippet[]
}

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

@customElement('split-layout-toggle')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    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 style="clear: right"></master-content>
        </div>
        <detail-content style="width: ${100 - sidebarWidthPercentage}%"></detail-content>
      </vaadin-split-layout>
    `;
  }

  toggleSidebar() {
    this.sidebarCollapsed = !this.sidebarCollapsed;
  }
  // end::snippet[]
}

Accessibility

The split handle can be focused and operated with the keyboard, allowing users to resize the content areas without a pointing device. Clicking the handle moves focus to it, while dragging it leaves focus unchanged so as not to interrupt pointer interaction.

When the handle has focus, it can be moved with the following keys:

Shortcut	Function
`Right` / `Down`	Grows the primary content area by a small step.
`Left` / `Up`	Shrinks the primary content area by a small step.
`Page Down`	Grows the primary content area by a larger step.
`Page Up`	Shrinks the primary content area by a larger step.
`Home`	Collapses the primary content area.
`End`	Collapses the secondary content area.

Shortcut

Function

Right / Down

Grows the primary content area by a small step.

Left / Up

Shrinks the primary content area by a small step.

Page Down

Grows the primary content area by a larger step.

Page Up

Shrinks the primary content area by a larger step.

Home

Collapses the primary content area.

End

Collapses the secondary content area.

The arrow key directions are reversed automatically for right-to-left languages.

The handle has a default accessible name, Resize separator, which can be customized:

Source code

JavaSplitLayout layout = new SplitLayout();

SplitLayoutI18n i18n = new SplitLayoutI18n()
        .setSeparator("Resize separator");
layout.setI18n(i18n);
HTML<vaadin-split-layout .i18n="${{ separator: 'Resize separator' }}"></vaadin-split-layout>
tsx<SplitLayout i18n={{ separator: 'Resize separator' }} />

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.

54c71610-9696-11ee-b9d1-0242ac120002

Docs

Docs

Split Layout

Orientation

Splitter Position

Accessibility

Best Practices