Vaadin Reference Card

This reference card is tailored to developers with previous Vaadin experience. It is a quick reference on key concepts and everyday tasks that arise while using the framework. For a comprehensive reference or tutorials to learn Vaadin, see the links in the Useful links section below.

Minimal application using Maven

pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>war</packaging>
    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
        <failOnMissingWebXml>false</failOnMissingWebXml>
    </properties>
    <dependencies>
        <dependency>
            <groupId>com.vaadin</groupId>
            <artifactId>vaadin-core</artifactId>
           <version>23.0.0</version>
        </dependency>
    </dependencies>
</project>

MainView.java:

import com.vaadin.flow.component.Text;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.router.Route;
@Route("demo") // localhost:8080/demo
public class MainView extends VerticalLayout {
    public MainView() {
        add(new Text("It works!"));
    }
}

UI Components

All Java UI components are instances of Component.

Input

CheckBox, ComboBox, DatePicker, Grid, TextField, TextArea, TimePicker, PasswordField, RadioButtonGroup, Upload, CustomField, EmailField, NumberField, RadioButton, Select, IntegerField, BigDecimalField, CheckBoxGroup, MultiSelectListBox, DateTimePicker.

Visualization and interaction

Accordion, Button, ContextMenu, Details, Dialog, Grid, Icon, Item, MenuBar, Notification, ProgressBar, Tabs, TreeGrid.

HTML

Div,  Span, Section, Header, Footer, Article, H1, H2, H3, H4, H5, H6, Paragraph, Label, Anchor, OrderedList, ListItem, Image, DescriptionList, Emphasis, Hr, IFrame, Input, Main, NativeButton, Nav, Pre, Section, UnorderedList.

Layouts

FlexLayout, HorizontalLayout, Scroller, VerticalLayout, SplitLayout, AppLayout, FormLayout, Login.

Mixin interfaces

UI components implement mixin interfaces with default methods to build up the functionality of the component. For example, CheckBox implements the HasSize, HasStyle, Focusable, ClickNotifier, and HasValueAndElement interfaces.

Sizing

Alignment

Alignment on the primary axis

Alignment on the secondary axis

AppLayout

Navigation

Parameters

@Route("")
public class GreetingView extends VerticalLayout
        implements HasUrlParameter<> {
    @Override
    public void setParameter(BeforeEvent event,
                              parameter) {
        String name = event.getLocation()
                .getQueryParameters()
                .getParameters()
                .get("name")
                .get(0);
        add(new Span(parameter + ", " + name));
    }
}

Navigation lifecycle

* Needs to be defined in a UI init listener if you want it to run before any views are created, for instance for general access control.

Forms and data binding

Binder is a helper class to set values in Java beans from input fields and vice versa.

new Binder<>(Person.class); // property names supported
new Binder<>(); // property names not supported

Java Bean Validation

BeanValidationBinder<Person> binder = new BeanValidationBinder<>(Person.class);
if (binder.validate().isOk()) {
    ...
}

Requires Java Bean Validation in the classpath

Basic configuration

binder.bind(textField, Person::getName, Person::setName);

Or:

binder.bind(
    textField,
    person -> person.getName(),
    (person, name) -> person.setName(name)
);

Binding

Two-way data binding. Sets the bean values in the input fields and sets values in the bean when the input fields values change:
binder.setBean(person);

One-way data binding. Sets values from the bean to the input fields:
binder.readBean(bean);

One-way data binding. Sets values from the input fields to the bean:
binder.writeBean(bean);

Gets the bean:
Person person = binder.getBean();

Advanced usage

binder.forField(ageTextField)
        .asRequired("Is required")
        .withNullRepresentation("")
        .withConverter(new StringToIntegerConverter(
                "Must be an integer"))
        .withValidator(age -> age > 0,
                "Must be a positive integer")
        .withStatusLabel(ageStatus)
        .bind(p -> p.getAge(), (p, age) -> p.setAge(age));
try {
    binder.writeBean(person);
    ...
} catch (ValidationException e) {
    ...
}

Bind by field name

Sessions, Views, and UIs

Using the Vaadin Session

Application lifecycle

Servlet customization

public class CustomServlet extends VaadinServlet {
    @Override
    protected void servletInitialized() throws ServletException {
        super.servletInitialized();
        ...your logic here...
    }
}

Register the servlet using @WebServlet or in the web.xml file.

Once per VaadinService instance

public class AppServiceInitListener
        implements VaadinServiceInitListener {

    @Override
    public void serviceInit(ServiceInitEvent event) {
        event.addBootstrapListener(response -> {
            ...change the bootstrap page...
        });

        event.addDependencyFilter((dependencies, filterContext) -> {
            ...add/remove/change client-side dependencies...
            return dependencies;
        });

        event.addRequestHandler((session, request, response) -> {
            ...change how responses are handled...
            return false;
        });
    }
}

In a Spring Boot project, it is sufficient to register this listener by adding the @Component annotation to the class.

In plain Java projects, the listener should be registered as a provider by adding the following file:

With the following content:
com.company.AppServiceInitListener

Session destroy listeners

public class ApplicationServiceInitListener
        implements VaadinServiceInitListener {

    @Override
    public void serviceInit(ServiceInitEvent initEvent) {
        initEvent.getSource().addSessionDestroyListener(
                sessionEvent -> {
            ... your logic here ...
        });
    }
}

UI component attach/detach

Use these methods to free resources and clean up:

public class CustomComponentOrView extends VerticalLayout {
    @Override
    protected void onAttach(AttachEvent attachEvent) {
        ...custom logic when the component is attached to the UI ...
    }
    @Override
    protected void onDetach(DetachEvent detachEvent) {
        ...custom logic when the component is detached from the UI...
    }
}

Heartbeat

The objective of the heartbeat mechanism is to remove UI instances that are no longer active in the same session.

The client-side sends keep-alive heartbeat requests at a configurable rate. A UI expires if three consecutive heartbeats are missed. 

Static content

Templates, CSS, Javascript, images:

Favicon:

Styling

Dark Theme

@Theme(value = Lumo.class, variant = Lumo.DARK)
public class MainView extends ... { }

Custom CSS

CSS (PROJECT_ROOT/frontend/css-file.css):
.css-class-name {
  ... custom css rules ...
}

Java (View.java):

...
@CssImport("./styles/css-file.css")
public class MainView extends ... {

    public MainView() {
        ...
        Button button = new Button();
        button.addClassName("css-class-name");
    }
}

Shadow DOM

Vaadin components are web components in the client side. The client-side implementation is encapsulated inside the Shadow DOM.

Java:

@CssImport(value = "./styles/styles.css", )
public class MainView extends VerticalLayout { ... }

CSS (styles.css):

[part="label"] {
    … custom CSS ...
}

Responsive design

Components such as AppLayout and FormLayout include responsive features. Use CSS media queries to fully customize layouts.

@media only screen and (min-width: 1024px) {
    html {
        … custom CSS ...
    }
}

Production builds

Performed with the vaadin-maven-plugin and the prepare-frontend and build-frontend goals. Projects created with the Maven archetype or on the Vaadin web site can activate a production build with mvn package -Pproduction.

Maven profile (all Vaadin starters include this profile):

<profile>
    <id>production</id>
    <properties>
        <vaadin.productionMode>true</vaadin.productionMode>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.vaadin</groupId>
            <artifactId>flow-server-production-mode</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>com.vaadin</groupId>
                <artifactId>vaadin-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <goals>
                            <goal>build-frontend</goal>
                        </goals>
                        <phase>compile</phase>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</profile>

A production build reduces the bundle size in several ways:

• Debugging information (main source maps) not included.
• The JS implementation is included only for components that are used (Java classes are analyzed).
• The script content is minified.
• The client-side bundle is gzipped.

Configuration properties