Documentation versions (currently viewingVaadin 14)

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

Creating a Simple Component Using the Template API

In this section, we demonstrate how to create a simple component using only the Template API.

Our example creates a simple view that allows the user to enter their name and click a button.

Creating the Template File on the Client Side

The first step is to create the LitElement TypeScript template file on the client side in frontend/src/hello-world.ts. This file contains the view structure.

Example: Creating the hello-world.ts TypeScript LitElement template file.

import {LitElement, html} from 'lit-element';
import '@vaadin/vaadin-text-field/vaadin-text-field.js';
import '@vaadin/vaadin-button/vaadin-button.js';
import '@axa-ch/input-text';

class HelloWorld extends LitElement {

    render() {
        return html`
                <vaadin-text-field id="firstInput"></vaadin-text-field>
                <axa-input-text id="secondInput"></axa-input-text>
                <vaadin-button id="helloButton">Click me!</vaadin-button>

customElements.define('hello-world', HelloWorld);
  • This is the JavaScript ES6 module that defines a LitElement template.

  • The tag name should contain at least one dash (-). For example, hello-world is a valid tag name, but helloworld is not.

  • The imported dependencies are:

    • LitElement (from the LitElement library): This is the required superclass of all LitElement templates.

    • vaadin-text-field, vaadin-button and axa-input-text components.

    • html for inline DOM templating.

Creating the Java Template Class

To use the client-side LitElement template on the server side, you need to create an associated Java class that extends the LitTemplate class.

Example: Creating the HelloWorld Java template class.

@NpmPackage(value = "@axa-ch/input-text", version = "4.3.11")
public class HelloWorld extends LitTemplate {

     * Creates the hello world template.
    public HelloWorld() {
  • The @Tag annotation name matches from the TypeScript template. This ensures that the tag name is the same on the server and the client.

  • The @JsModule annotation binds the Java class to the hello-world.ts template class by specifying the relative path to the JavaScript module in the frontend folder in the project root. You can import multiple resources using the @JsModule annotation, if needed.

  • The @NpmPackage annotation declares a dependency to the input-text npm package: @axa-ch/input-text 4.3.11. This annotation can be used to declare a dependency to any npm package.

Using the Component

You can now use the HelloWorld component in the same way as any other component.

Example: Using the HelloWorld component in a Java class.

HelloWorld hello = new HelloWorld();

Div layout = new Div();
Some browsers, like IE11 and Safari 9, do not support ES modules. To ensure that your component works in these browsers, you can configure this in the vaadin-maven-plugin in your pom.xml. See Taking your Application into Production for more.