Documentation versions (currently viewingVaadin 24)

Creating a Component Using Templates

How to create a component using only the Template API.

This section demonstrates how to create a component using only the Template API.

This example creates a 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 { html, LitElement } from 'lit';
import '@vaadin/button';
import '@vaadin/text-field';
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 isn’t.

  • 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 on the input-text npm package: @axa-ch/input-text 4.3.11. This annotation can be used to declare a dependency on 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();