Creating Web Component

LIVE DEMO

You can create Web Components from scratch or by extending existing Vaadin web components. After the client-side component is implemented, you can create a Java API for it.

The example below shows how to build a light/dark theme toggle by extending the Vaadin button component and adding theme-switching behavior with Lit.

Creating JavaScript Web Component

Create the theme-toggle.js file in the frontend/src/component/theme-toggle folder. It contains a Web Component implementing the light/dark theme toggle.

import {html} from 'lit';
import {Button} from '@vaadin/button';
import {defineCustomElement} from '@vaadin/component-base/src/define.js';

export class ThemeToggle extends Button { (1)

    static get is() {
        return 'theme-toggle'; (2)
    }

    static get template() { (3)
        return html`
            <div class="vaadin-button-container">
                <span part="prefix" aria-hidden="true">
                    <slot name="prefix"></slot>
                </span>
                <span part="label">
                    <slot></slot>
                </span>
            </div>

            <slot name="tooltip"></slot>
        `;
    }

    static get properties() { (4)
        return {
            ariaLabel: {
                type: String,
                value: 'Theme toggle',
                reflectToAttribute: true,
            },
            storageKey: {
                type: String,
                value: 'jmix.flowui.theme',
                observer: '_onStorageKeyChanged'
            }
        };
    }

    constructor() {
        super();

        this.addEventListener('click', () => this.toggleTheme());
        this.addEventListener('click', () => {
            const customEvent = new CustomEvent('theme-changed', {detail: {value: this.getCurrentTheme()}});
            this.dispatchEvent(customEvent); (5)
        });
    }

    /** @protected */
    ready() {
        super.ready();
        this.applyStorageTheme();
    }

    applyStorageTheme() {
        let storageTheme = this.getStorageTheme();
        let currentTheme = this.getCurrentTheme();
        if (storageTheme && currentTheme !== storageTheme) {
            this.applyTheme(storageTheme);
        }
    }

    getStorageTheme() {
        return localStorage.getItem(this.storageKey);
    }

    getCurrentTheme() {
        return document.documentElement.getAttribute('theme');
    }

    toggleTheme() {
        const theme = this.getCurrentTheme();
        this.applyTheme(theme === 'dark' ? '' : 'dark');
    }

    applyTheme(theme) {
        document.documentElement.setAttribute('theme', theme);
        localStorage.setItem(this.storageKey, theme);
    }

    /** @protected */
    _onStorageKeyChanged(storageKey, oldStorageKey) {
        const theme = localStorage.getItem(oldStorageKey);
        localStorage.removeItem(oldStorageKey);

        if (theme) {
            localStorage.setItem(storageKey, theme);
        }
    }
}

defineCustomElement(ThemeToggle); (6)
1 Extends Vaadin Button to reuse button behavior and styling.
2 Defines the name of HTML element.
3 Defines the Shadow DOM template, including slots for the icon, text, and tooltip.
4 Defines client-side properties, including the local storage key used to persist the selected theme.
5 Dispatches the theme-changed event after the component switches the theme.
6 Exports the custom HTML element with the name defined in the static get is() method.

Creating Java API for Web Component

Create the ThemeToggle.java file which is a UI component class. It defines an API for the server code, accessor methods, event listeners, and data sources connection.

import com.vaadin.flow.component.*;
import com.vaadin.flow.component.dependency.JsModule;
import com.vaadin.flow.component.icon.Icon;
import com.vaadin.flow.component.icon.VaadinIcon;
import com.vaadin.flow.component.shared.HasTooltip;
import com.vaadin.flow.dom.Element;
import com.vaadin.flow.shared.Registration;
import io.jmix.flowui.kit.component.HasTitle;

import java.util.Set;
import java.util.function.Predicate;
import java.util.stream.Collectors;
import java.util.stream.Stream;

@Tag("theme-toggle") (1)
@JsModule("./src/component/theme-toggle/theme-toggle.js") (2)
public class ThemeToggle extends Component implements ClickNotifier<ThemeToggle>,
        Focusable<ThemeToggle>, HasTheme, HasEnabled, HasSize, HasStyle,
        HasText, HasTooltip, HasTitle, HasAriaLabel { (3)

    public static final String STORAGE_KEY_PROPERTY = "storageKey";
    public static final String THEME_CHANGED_EVENT = "theme-changed";
    protected Component iconComponent;

    public ThemeToggle() {
        setIcon(createDefaultIcon());
    }

    public ThemeToggle(Component icon) {
        setIcon(icon);
    }

    public ThemeToggle(String text, Component icon) {
        setIcon(icon);
        setText(text);
    }

    protected Icon createDefaultIcon() {
        Icon icon = VaadinIcon.ADJUST.create();
        icon.getElement().getStyle().set("rotate", "180deg");
        return icon;
    }

    @Override
    public void setText(String text) {
        removeAll(getNonTextNodes());
        if (text != null && !text.isEmpty()) {
            getElement().appendChild(Element.createText(text));
        }
        updateThemeAttribute();
    }

    public Component getIcon() {
        return iconComponent;
    }

    public void setIcon(Component icon) {
        if (icon != null && icon.getElement().isTextNode()) {
            throw new IllegalArgumentException("Text node can't be used as an icon.");
        }
        if (iconComponent != null) {
            remove(iconComponent);
        }

        iconComponent = icon;
        if (icon != null) {
            add(icon);
            updateIconSlot();
        }

        updateThemeAttribute();
    }

    protected void updateIconSlot() {
        iconComponent.getElement().setAttribute("slot", "prefix");
    }

    protected void add(Component... components) {
        for (Component component : components) {
            getElement().appendChild(component.getElement());
        }
    }

    protected void remove(Component... components) {
        for (Component component : components) {
            if (getElement().equals(component.getElement().getParent())) {
                component.getElement().removeAttribute("slot");
                getElement().removeChild(component.getElement());
            } else {
                throw new IllegalArgumentException(
                        "The given component (" + component + ") is not a child of this component");
            }
        }
    }

    public boolean isAutofocus() {
        return getElement().getProperty("autofocus", false);
    }

    public void setAutofocus(boolean autofocus) {
        getElement().setProperty("autofocus", autofocus);
    }

    public String getStorageKey() {
        return getElement().getProperty(STORAGE_KEY_PROPERTY);
    }

    public void setStorageKey(String storageKey) {
        getElement().setProperty(STORAGE_KEY_PROPERTY, storageKey);
    }

    protected void removeAll(Element... exclusion) {
        Set<Element> toExclude = Stream.of(exclusion)
                .collect(Collectors.toSet());
        Predicate<Element> filter = toExclude::contains;

        getElement().getChildren()
                .filter(filter.negate())
                .forEach(child -> child.removeAttribute("slot"));

        getElement().removeAllChildren();
        getElement().appendChild(exclusion);
    }

    protected Element[] getNonTextNodes() {
        return getElement().getChildren()
                .filter(element -> !element.isTextNode())
                .toArray(Element[]::new);
    }

    protected void updateThemeAttribute() {
        long childCount = getElement().getChildren()
                .filter(element ->
                        element.isTextNode() || !"vaadin-tooltip".equals(element.getTag()))
                .count();

        if (childCount == 1 && iconComponent != null) {
            getThemeNames().add("icon");
        } else {
            getThemeNames().remove("icon");
        }
    }

    public Registration addThemeChangeListener(ComponentEventListener<ThemeToggleThemeChangedEvent> listener) {
        return addListener(ThemeToggleThemeChangedEvent.class, listener);
    }

    @DomEvent(THEME_CHANGED_EVENT) (4)
    public static class ThemeToggleThemeChangedEvent extends ComponentEvent<ThemeToggle> {

        protected String value;

        public ThemeToggleThemeChangedEvent(ThemeToggle source, boolean fromClient,
                                            @EventData("event.detail.value") String value) { (5)
            super(source, fromClient);
            this.value = value;
        }

        public String getValue() {
            return value;
        }
    }
}
1 Defines the root element that is created automatically by the Component class and can be accessed using the getElement() method. Must be the same as the Web Component exports.
2 The @JsModule annotation defines the import of the JavaScript module.
3 Using Vaadin Mixin Interfaces to provide common APIs and default behavior for sets of functionalities found in most Web Components.
4 Using the @DomEvent annotation to connect a ThemeToggle component to the theme-changed DOM event.
5 Using the @EventData annotation to define additional event data, the theme value in this case.
More information about creating custom components can be found in Vaadin documentation: Creating Components, Using Vaadin Mixin Interfaces, Using Events with Components.

Usage Example

After a component is implemented it can be used in views either in XML descriptors or programmatically, for example:

XML Descriptor

<view xmlns="http://jmix.io/schema/flowui/view"
      xmlns:app="http://company.com/schema/app-ui-components"
      title="msg://themeToggleView.title"> (1)
    <layout>
        <app:themeToggle text="Click to switch theme"/> (2)
    </layout>
</view>
1 Defines a namespace with the same value as in the xmlns and targetNamespace attributes of the component’s XSD.
2 Adds the themeToggle element with the namespace prefix.

Programmatic Usage

@Subscribe
public void onInit(final InitEvent event) {
    ThemeToggle themeToggle = new ThemeToggle();
    themeToggle.setText("Click to switch theme");
    themeToggle.addThemeChangeListener(changedEvent ->
            notifications.create("Theme switched: " + getThemeValue(changedEvent))
                    .withPosition(Notification.Position.TOP_CENTER)
                    .show());
    getContent().add(themeToggle);
}