Documentation versions (currently viewingVaadin 14)

You are viewing documentation for an older Vaadin version. View latest documentation

Differences Between Vaadin 10+ and 8 Applications

This page describes the essential differences between applications using Vaadin versions 10 and later, in comparison to those using Vaadin version 8.

The UI Class is Different and it is Optional

A subclass of UI is not needed anymore in Vaadin 10+ applications. It is still there, but it is not the starting point of the application anymore, and you don’t need to define your custom UI. Adding the content to show is handled by Router which is introduced in the next chapter.

Most things you have previously been done by subclassing UI can be achieved in alternative ways that are based on composition instead of inheritance, or by configuring things through a router layout class that is used by all views in the application. These alternatives are covered in this documentation, but if some information is missing, please create an issue so we may add the necessary information.

In Vaadin 7 and 8, the UI referenced a <div> element which was a child of the <body> in the DOM. In Vaadin platform, the UI is instead directly connected to to the <body> element.

The API in the UI class in Vaadin 10+ has gone through a clean-up and some API that is not meant for application developers to access has been moved to internal classes. For using API that is still in UI, the same UI.getCurrent() call can still be used to obtain a reference to the UI for the currently active request.

The @PreserveOnRefresh annotation in Vaadin 7 and 8 was added to the UI subclass. In Vaadin 10+, the @PreserveOnRefresh annotation should be added to the view class or router layout class. As a consequence, a typical pattern of storing data via reference to the UI class cannot be used with Vaadin 10+. For details on this, see preserving state on refresh.

While migrating, you still might want to create your own UI, and you can see an example for that in the next topic.

The Servlet Definition is Optional

Similarly as the UI, the servlet definition is optional in Vaadin 10+. And the reason is also the same, the new Routing API, which is introduced in the next chapter. By default the servlet is automatically mapped to the root context path. You can of course still configure the servlet yourself, and it happens the same way as previously:

@WebServlet(urlPatterns = "/*", name = "myservlet", asyncSupported = true,
// Example on initialization parameter configuration
initParams = {
        @WebInitParam(name = "frontend.url.es6", value = ""),
        @WebInitParam(name = "frontend.url.es5", value = "") })
// The UI configuration is optional
@VaadinServletConfiguration(ui = MyUI.class, productionMode = false)
public class MyServlet extends VaadinServlet {

// this is not necessary anymore, but might help you get started with migration
public class MyUI extends UI {
    protected void init(VaadinRequest request) {
        // do initial steps here.
        // previously routing

Single Step Bootstrap and No UIProvider

In Vaadin 8, the application bootstrap happened in two phases. The initial page response only contained code to obtain more data related to the browser, data which was not available in the initial request. Based on this, the correct UI would be created. This was a good option back then, since the capabilities of mobile devices required their completely own client engine and UI to deliver the best possible end user experience.

This is not necessary anymore, and in Vaadin 10+ the UI content is delivered on the first response and the application is bootstrapped without further network activity. This means that UIProvider has become obsolete.

Modifying the Bootstrap Page

If you had previously customized the initial response with BootstrapListener, this tutorial show the new and simpler way of customizing the initial page response using PageConfigurator or specific annotations on the application’s main layout.

BoostrapListener is still there and can be registered using a VaadinServiceInitListener, as shown by this tutorial.

Configuring Server Push

As a custom UI class is no longer needed, you can configure the used PushMode for your app in the main layout of your application. See the Server Push Configuration tutorial for more info.

Loading Indicator Configuration

The default loading indicator is the same as in Vaadin 8 Valo Theme. If you want to customize it or disable it, you should see the loading indicator documentation.

Similarities & Package Naming

Some of the Java code in Vaadin 10+ is directly inherited from Vaadin 8. Even in these cases, the package names are however changed. This is because we want to make it possible to use Vaadin 8 components and views without classpath conflicts inside Vaadin 10+ using Multiplatform Runtime. Thus the package names for Vaadin 10+ contain flow that separates them from the Vaadin 8 packages.