Documentation versions (currently viewingVaadin 8)

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Custom Layouts

While it is possible to create almost any typical layout with the standard layout components, it is sometimes best to separate the layout completely from code. With the CustomLayout component, you can write your layout as a template in HTML that provides locations of any contained components. The layout template is included in a theme. This separation allows the layout to be designed separately from code, for example using WYSIWYG web designer tools such as Adobe Dreamweaver.

A template is a HTML file located under layouts folder under a theme folder under the /VAADIN/themes/ folder, for example, /VAADIN/themes/themename/layouts/mylayout.html. (Notice that the root path /VAADIN/themes/ for themes is fixed.) A template can also be provided dynamically from an InputStream, as explained below. A template includes <div> elements with a data-location or location attribute that defines the location identifier. All custom layout HTML-files must be saved using UTF-8 character encoding.

<table width="100%" height="100%">
  <tr height="100%">
      <table align="center">
          <td align="right">User&nbsp;name:</td>
          <td><div data-location="username"></div></td>
          <td align="right">Password:</td>
          <td><div data-location="password"></div></td>
    <td align="right" colspan="2">
      <div data-location="okbutton"></div>

The client-side engine of Vaadin will replace contents of the location elements with the components. The components are bound to the location elements by the location identifier given to addComponent(), as shown in the example below.

Panel loginPanel = new Panel("Login");
CustomLayout content = new CustomLayout("layoutname");

// No captions for fields is they are provided in the template
content.addComponent(new TextField(), "username");
content.addComponent(new TextField(), "password");
content.addComponent(new Button("Login"), "okbutton");

The resulting layout is shown below in Example of a Custom Layout Component.

customlayout example1
Example of a Custom Layout Component

You can use addComponent() also to replace an existing component in the location given in the second parameter.

In addition to a static template file, you can provide a template dynamically with the CustomLayout constructor that accepts an InputStream as the template source. For example:

new CustomLayout(new ByteArrayInputStream("<b>Template</b>".getBytes()));


new CustomLayout(new FileInputStream(file));