Components in Vaadin platform
While all the components have been rebuilt based on Web Components, there are some components that don’t yet have a replacement with server side Java API. The ones that have, might have gone through some changes. Some older features might have been removed.
|Watch the Vaadin 10+: Intro free training video to learn more about the Vaadin platform terminology and what Vaadin components are.|
The following table lists the existing Vaadin 8 components and their direct replacements in the Vaadin platform. Note that the replacement component might not have 1-1 feature parity. If no replacement is yet available, current plans or options for replacement is mentioned.
|The mentioned components are available starting from Vaadin 10 or from the specifically mentioned platform version.|
Not planned. Similar functionality in Vaadin platform can be achieved using eg.
Use the native
ContextMenu (official add-on)
Div & FlexLayout
More details later in this chapter
AbstractField, AbstractCompositeField or AbstractSinglePropertyField
HTML or PolymerTemplate
See notes below.
See detailed notes about replacement alternatives below. Search Directory or contact us
Demo, more details later in this chapter
Search Directory or contact us
Search Directory or contact us
Text or Span
There is also a
LoginForm or LoginOverlay (V13)
Similar add-on available, search for "Card" in vaadin.com/directory. Candidate for adding to 14.x in 2020.
Planned. Can be made by combining
There are Web Components available, check vaadin.com/directory. You can also use DOM API and
TextField (BigDecimalField, IntegerField, NumberField)
Planned, add-on available, no timeline for integration yet. Go vote issue or contact us if you need it
Can be built as a composite using
Can directly use the native
Demo, more details later in this chapter
Not mandatory in 10+. Replaced with root layout and
Demo Note that there is only limited support due to missing eg. minimize / maximize feature.
|In case you are missing any component, search Directory for 3rd party add-on or contact us for help.|
For any missing components, you should first look for alternatives in vaadin.com/directory. It shows both Vaadin platform add-ons with Java API and web components that can be integrated to Java.
For the components that are available in Vaadin platform, you can browse vaadin.com/components/browse for features and examples.
Basic Component Features
The way components are structured has been renewed in Vaadin platform. While the basics stay the same, backwards compatibility has been discarded in favor of optimizing for current and future usage.
In Vaadin 8, there was a large and complex class hierarchy for components, and the
Component interface already declared a large set of API that components were supposed to support. This meant that almost every time, the component had to extend at least
AbstractComponent so that they would not need to implement all the methods from the interface. That would mean that there would be a lot of API in the actual component, some of which made no sense in all cases.
In Vaadin Flow the
Component is an abstract class, with only the minimal set of API exposed. For the component implementations, it is up to them to pick up pieces of API as mixin interfaces that provide default implementations.
Component is Lightweight and it Maps to an Element
Every Vaadin Flow component always maps to one root element in the server-side DOM representation. A component can contain multiple components or elements inside it. The component is the high level API for application developers to compose UIs efficiently. The Element API is the low level API used to build components. The Element API makes it possible to modify the DOM easily from the server side.
If you look up the
Component class in Vaadin Flow, you notice that there is no API even for setting the width or height of the component!
For your own components, add the API by implementing the
HasSize mixin interface,
which has default implementations for e.g.
setWidth(String width) and
So by adding two words of code you can achieve full sizing capabilities for your components.
See the Creating A Simple Component Using the Element API tutorial for more info.
All Components Don’t Have Captions or Icons
In Vaadin 8 every component had a caption. The caption was usually shown next to the component, based on the parent layout’s caption handling implementation. The caption could optionally be rendered with an icon. Some layouts didn’t support showing captions and/or icons.
In Vaadin platform there is no universal caption concept anymore. Some components might have a similar feature,
but that it is always component specific. Usually that API is
setLabel(String label) instead of
Some layouts, such as
FormLayout, also support showing a label text or component for each child component.
In other cases, you can create your own
Text component to contain the caption text and add it to the parent layout alongside the component.
Adding icons is possible, it is just HTML5 after all. But as with caption there is no universal support for that.
setEnabled(boolean enabled) is Still a Server Side Security Feature
In Vaadin 10+, the
setEnabled method is specific to components marked with the
HasEnabled mixin interface (which comes also with
When a component is disabled, by default, any property changes and DOM events coming from the client side are ignored.
However, it is possible to whitelist some properties and events to be allowed if necessary.
The disabled state is automatically cascaded to child components it is up to the component to change the disabled UX to mark the component as "not-working" when it has been disabled. Changes from the client are still always blocked for disabled components even if the component isn’t implemented to appear disabled. All relevant Vaadin components change their looks when disabled.
Read the Component Enabled State tutorial for more details.
setReadOnly(boolean readOnly) is Component Specific and Works Differently
In Flow the
setReadOnly(boolean readOnly) method is specific to components accepting user input by implementing
For a readonly component, changes from the client will not make the return value of
getValue() to change nor fire any
Most components will also update their visual status to indicate to the user that the value cannot be changed.
Layouts in Platform
In Vaadin 8 the layouting of components was managed by a
LayoutManager on the client engine.
This has its roots in a time when the differences between browsers were big,
and the legacy Framework still supported Internet Explorer versions that worked by their own rules.
Creating your own layouts was quite complex since it always required writing custom client side code with GWT.
In Vaadin platform, there is no more LayoutManager to do calculations in browser. All layouts are self-contained and mostly just rely on the HTML5 and CSS3 standards, which all modern browsers (as well as IE 11) support. Responsive layouts can be created now using the DOM API in Java on the server side.
As native browser features are used for rendering, layouts are rendered faster than in previous versions.
Core Layouts API and Creating Custom Layouts
In Vaadin platform you can create a custom layout with only server side Java code by using mixin-interfaces and the Element API. The mixin-interfaces are also the basis for the core layouts and replace a complex class hierarchy from Vaadin 8:
HasComponentsfor simply adding components to the parent’s root Element with:
HasOrderedComponentsfor accessing components based on index
All the core layouts except
Div are based on Web Components, but they still give a good example on how to create your own layouts if needed.
For Element API usage, please see the Creating a Component Which Can Contain Other Components tutorial.
Layout Click Listeners
There is currently no direct API exposed for this in the layouts. But if you want to, you can access the element and add a DOM event listener to it for click events. If this is a much requested API, we could make it a standard feature to the layouts. There is an enhancement issue for this.
Available Layouts in Platform
HorizontalLayout & VerticalLayout
These map to the
align-itemsCSS property values.
Spacing and Padding are only available as on/off for all edges of the layout, instead of separately for top/right/bottom/left. Fine-grained control is available using CSS, e.g.
setWidth("100%")for any contained component will not have the same effect as before - it will cause the component to get the full size of the parent layout, instead of full size of the slot. Instead, leave the size undefined and
flex-growwill take care of sizing the component.
For better understanding how to use the
expand() methods and how the flex layouts work,
please see the Mozilla Foundation documentation on CSS flex.
FormLayout has been made responsive and it now supports multiple columns. Thus it also in some ways replaces the old
This layout is a server side convenience API for using a
display: flex and then setting the flexbox properties via Java.
If you haven’t already, you should introduce yourself to flexbox. It will allow you to easily build more responsive layouts.
Div AKA CssLayout
The most powerful layout of Vaadin 8 in terms of customizability is the
CssLayout, which is just a
<div> element in the browser.
This is now also available, but it is now named to what is actually is - a
Div element in the browser.
getCss method from V8 is not available, but in Vaadin platform you can easily modify the element CSS from the server side for any component using
component.getElement().getStyle(). This works with any layout, not only
Replacing Existing Layouts
In addition to the options listed below, you should also see if directory has add-ons available that can be used as a replacement. In case you need a custom component implementation, contact us for help.
AbsoluteLayout can be replaced with the
Div component and then applying the CSS properties
and coordinates as top/right/bottom/left properties to the components added inside it using the Element API.
There is currently no direct replacement, but depending on your use case, you could replace the old
GridLayout with either
Boardwhich is commercial and fully responsive
FormLayoutwhich now supports multiple columns
FlexLayoutwhich is powerful but requires mastering the flexbox concepts
Divtogether with the new CSS Grid functionality that is supported in most browsers
Migrating Your Own Components
One of the biggest improvements in Vaadin Flow compared to Vaadin 8 is making it possible to access and customize the DOM from server-side Java. This obsoletes many reasons for using GWT for creating components. It also means that existing custom components from V8 have to be rebuilt again. The server side API can be reused, but some changes may be needed since the class hierarchy has changed in Flow.
Simple components can be composed using existing components and the Element API. The creating components tutorials have examples on this. For more complex components, with lots of client side logic or a complex DOM structure, it might be better to implement them as Web Components and provide a Java API to those.