Documentation

Documentation

Integrating Web Components

How to create new HTML tags with custom names.

Web Components are a collection of web standards that allow you to create new HTML tags with custom names. They’re reusable and provide full encapsulation of styles and markup. See Introduction to Web Components for more information on how it works. This page, however, explains how to integrate it into your projects.

To use a Web Component in Vaadin, you first have to load the HTML, JavaScript, and CSS files needed by the component. This is explained below. Then you need to employ a Java API to configure the component, from which to listen for events. See Creating a Java API for a Web Component for more information on that.

The Web Component’s client-side files — typically JavaScript module files — are available using npm, which Vaadin supports by default. It automatically installs and uses npm packages. It also serves the static files to the browser.

Tip
Using pnpm or bun instead of npm
Vaadin also supports using pnpm (known as performant npm) or bun. See Configuring npm/pnpm/bun for details.

Integrating a JS Module into Vaadin

Although you can create all of the files manually, the easiest way is to use the Vaadin Add-on Starter. This gives you a project with all of the necessary dependencies. It also provides an npm import for the selected component, as well as a stub component Java class for your Web Component integration. And it gives you a Maven profile that handles everything necessary to deploy the component to Vaadin Directory.

The following is an example of annotations in the Java component class as a starter project for the mwc-slider Web Component:

@Tag("mwc-slider")
@NpmPackage(value = "@material/mwc-slider",
            version = "0.27.0")
@JsModule("@material/mwc-slider/slider.js")

The @Tag annotation here defines the name of the HTML element. The @JSModule and @NpmPackage annotations define the import of the JavaScript module.

Adding Frontend Files

Your component may require in-project frontend files, such as additional JavaScript modules. In which case, add them to the src/main/resources/META-INF/frontend directory so that they’re packaged in the component JAR if you choose to make an add-on of your component.

As a example, you might use the @JsModule annotation to add a local JavaScript module like so:

@JsModule("./my-local-module.js")

When running mvn clean install, the vaadin-maven-plugin automatically installs the npm package in node_modules and imports the JavaScript module file into the document provided to the browser. Additionally, if you run the Jetty web server from Maven (i.e., using mvn jetty:run), your project’s source code is monitored for changes to these types of annotations. Any change to @NpmPackage or @JsModule annotations triggers installation of the referenced packages and hot deployment of your application, including the new JS module imports.

Understanding the Project Files

The project includes the AddonView component class at src/test/java/…/AddonView.java:

@Route("")
public class AddonView extends Div {
  ...
}

This project set-up is slightly unconventional to allow it to be a single-module Maven project. It uses the test folder both for the demo application and for the actual test files. When you run mvn jetty:run in the project, it deploys AddonView and displays it at http://localhost:8080.

Once you’ve done all of this, your project is ready for you to proceed to creating the Java API. See Creating a Java API for a Web Component for how to do this.

Note
Web Components may not show a UI
Some Web Components don’t show a UI when they are added to the page as empty tags. If the addon view is empty, use the browser console to verify that all files were found (i.e., no 404 errors) and then check that the component is correctly configured. See Debugging a Web Component Integration for more.
Note
Project setup isn’t configured for deployment
Although the project setup is easy to use for development and testing, it doesn’t allow you easily to produce a demo WAR file for deployment. It’s usually better to create a separate project — or to convert the project into a multi-module project — for this purpose. The demo files included in the starter are intended as test UIs, whereas your result should be aimed at the end user.
Important
Source monitoring doesn’t work in a multi-module project
If your project is configured as a multi-module project, for example because the base project is an older version or you have manually converted it, source monitoring won’t work. Moreover, changes to the component aren’t automatically reflected in your demo application.

Deploying the Add-on to the Vaadin Directory

When you’re satisfied with the API, you can make the add-on available to everyone by deploying it to the Vaadin Directory.

To create a directory-compatible add-on package, execute the following:

mvn clean install -Pdirectory

This creates a ZIP file in the target directory.

To add your add-on to the Vaadin Directory, you’ll need to do the following:

  • Login or register at https://vaadin.com/directory.

  • Then, upload the ZIP file.

  • Write an overview of your add-on to let others know what it can do, which browsers are supported, and any other relevant information.

When finished, you may publish your add-on. Users can use your add-on by copying the dependency information from the add-on page in the directory.

Note
Make sure to keep metadata up to date
The metadata used by the Vaadin Directory is defined in assembly/MANIFEST.MF, based on the project’s metadata. If you make changes to the project (e.g., by removing <name></name>), make sure to update the metadata, as well.

Creating Other Add-on Types

You can also use the Add-on Starter to create different kinds of add-ons (e.g., to create a data provider). To create a generic project that can be used for any add-on, do the following:

  • Leave the default Web Component URL in the starter form;

  • Download the project; and then

  • Delete the @NpmPackage and @JsModule annotations, and the UI component class.