Late last year, we announced that we are gradually moving away from Google's Polymer JavaScript library in favor of the far more lightweight and performant LitElement library. The next LTS, which is currently targeted for the latter half of 2021, will make Polymer optional for HTML templates. Using LitElement for template-based views allows faster rendering of your app views. We aim to eventually make the Polymer dependency completely optional (opt-in), which will result in smaller bundle sizes and a lower network footprint for Vaadin applications. The timing of this depends on when we complete the component set transition to LitElement - we will keep you posted. In any event, Polymer support continues in the next LTS.
Let's go through the planned changes and how they affect you as an application developer using Polymer templates in Vaadin.
Vaadin components on LitElement
We have started migrating Vaadin components to LitElement. The changes only affect the internal implementation of the components and leave 99% of the public API intact. Read more about this in The next generation of Vaadin web components.
LitElement and lit-html as the template format
With LitElement comes a new format for templates used in Vaadin. The template format used in LitElement is defined by lit-html - a templating library for rendering and updating HTML.
There are two ways you can use LitElement templates: combined with Java UI logic or combined with TypeScript UI logic.
Templates and server-side Java
When using LitElement with Java UI logic, you use a LitElement template without any JS/TS logic - simply as a static HTML template.
// hello-world.ts
import { customElement, html, LitElement } from 'lit-element';
import '@vaadin/vaadin-button/vaadin-button';
import '@vaadin/vaadin-text-field/vaadin-text-field';
import '@vaadin/vaadin-ordered-layout/vaadin-vertical-layout';
@customElement('hello-world')
class HelloWorld extends LitElement {
render() {
return html`
<vaadin-vertical-layout theme="margin spacing">
<vaadin-text-field label="Name" id="nameField"></vaadin-text-field>
<vaadin-button id="helloButton">Say Hello</vaadin-button>
</vaadin-vertical-layout>`;
}
}
You bind server-side instances to the components with @Id annotations in a Java class that extends LitTemplate. LitTemplate is a Vaadin component that renders a LitElement template. The components you bind to the server-side class are accessible in Java, so you can add event listeners, access data on the server-side, and change component states programmatically.
// HelloWorld.java
@Tag("hello-world")
@JsModule("./hello-world.ts")
public class HelloWorld extends LitTemplate {
@Id
// Uses the vaadin-button id "helloButton"
private Button helloButton;
@Id
private TextField nameField;
public HelloWorld() {
helloButton.addClickListener(event -> Notification.show("Hello " + nameField.getValue()));
}
}
LitTemplate is available in Vaadin 17 beta and will be included in Vaadin 14 later. Vaadin 17 stable version will be available on September 2nd, 2020. Read the documentation on how to create templates with LitElement and Vaadin Java API.
Templates and client-side TypeScript
In Vaadin 15, we introduced the possibility to create client-side views with LitElement and TypeScript, and connect them to a Java backend with end-to-end type safety. Vaadin 17 added essential helpers for form data binding with validation.
When using LitElement for client-side views, you create your UI from LitElement-based components and write the UI logic in TypeScript. Here’s the equivalent client-side version of the previous Hello World example.
// hello-world.ts
import { customElement, html, LitElement } from "lit-element";
import "@vaadin/vaadin-button/vaadin-button";
import "@vaadin/vaadin-text-field/vaadin-text-field";
import "@vaadin/vaadin-ordered-layout/vaadin-vertical-layout";
import { showNotification } from "@vaadin/flow-frontend/a-notification";
@customElement('hello-world')
export class HelloWorld extends LitElement {
name: string = "";
render() {
return html`
<vaadin-vertical-layout theme="padding spacing">
<vaadin-text-field
label="Your name"
@value-changed="${this.nameChanged}"
></vaadin-text-field>
<vaadin-button @click="${this.sayHello}">Say hello</vaadin-button>
</vaadin-vertical-layout>
`;
}
nameChanged(e: CustomEvent) {
this.name = e.detail.value;
}
sayHello() {
showNotification("Hello " + this.name);
}
}
You then would hook up your components to backend business logic and data through Vaadin endpoints. The framework takes care of type safety, security and data validation. Read Creating Forms with TypeScript and LitElement for more about form data binding.
Migration and how to prepare for the future
The Polymer dependency, together with the PolymerTemplate class, remains in the next LTS as an optional dependency, which means that you don’t need to migrate.
Although it is not necessary to migrate to LitElement by the next LTS, we recommend using LitTemplate for any new templates you create. As of today, you still need to create the templates by hand (and they are not available in Vaadin 14), but we are working towards important milestones in relation to template support:
- We will release the LitTemplate feature in Vaadin 14. The backport from Vaadin 17 has been planned, but we don’t have a target date as yet.
- There is a limitation where any configuration you set for a component in the template is rendered correctly, but the component state on the server-side is not affected. This limitation affects both PolymerTemplate and LitTemplate. We will add support for synchronizing the initial state of the components from the template to the server-side. Currently, it’s targeted for Vaadin 18.
- We need to release a version of Vaadin Designer that supports LitElement for those who prefer to use a drag-and-drop editor to create their templates. A new Designer version is in the works and targeted for mid October.