Using Components in Fusion

This article describes using Vaadin components and/or third-party web components in your Fusion views.

The examples assume a running Fusion application. For information on setting up a Fusion project and defining a basic view, see the Quick Start Tutorial. For a full list of components and detailed API documentation, see the Design System Components section.

Using Components From Vaadin

When bootstrapping a Fusion project from an official starter, all Vaadin components frontend packages are automatically installed. To use a component in your own view, it is enough to import it into the view .ts file. For example:

import '@vaadin/vaadin-text-field';

You can then use the Text Field component (the <vaadin-text-field> element) in your view’s render method:

render() {
  return html`
    <vaadin-text-field id='firstname' label='First name'></vaadin-text-field>
    <vaadin-text-field id='lastname' label='Last name'></vaadin-text-field>
  `;
}

Component Class

The class name of a <vaadin-component-name> element follows the pattern ComponentNameElement Importing the class gives a type safe access to the component’s API. For example:

import { html, LitElement } from 'lit';
import { customElement, query } from 'lit/decorators.js';

import '@vaadin/vaadin-combo-box';
import '@vaadin/vaadin-checkbox';
import { ComboBoxElement } from '@vaadin/vaadin-combo-box';
import { CheckboxElement } from '@vaadin/vaadin-checkbox';

@customElement('greeting-view')
export class GreetingView extends LitElement {
  @query('#greeting')
  greeting!: ComboBoxElement;

  @query('#custom')
  custom!: CheckboxElement;

  render() {
    return html`
      <vaadin-combo-box
        id="greeting"
        label="Greeting"
        items='["Hi", "Hello", "Dear"]'
        value="Hi"
      ></vaadin-combo-box>
      <vaadin-checkbox id="custom" @checked-changed="${this.checkboxChanged}"
        >Type Custom greeting</vaadin-checkbox
      >
    `;
  }

  checkboxChanged() {
    this.greeting.allowCustomValue = this.custom.checked;
    if (!this.greeting.allowCustomValue) {
      this.greeting.value = this.greeting.items![0] as string;
    }
  }
}

In the above example, the Combo Box and Checkbox components with IDs greeting and custom respectively are mapped to typed class variables of the same names via the @query decorator. The Checkbox event listener toggles the allowCustomValue attribute of the Combo Box, which defines whether the user can enter custom values into the field or is constrained to the alternatives in the items overlay. Having strongly typed class variables helps to catch errors at compile time and allows IDE code completion.

HTML Attributes

The following HTML attributes work as expected with all Vaadin components:

PropertyDescription

enabled

Whether the component is enabled; a disabled component cannot be interacted with.

title

Additional label associated with the component, shown as a tooltip.

visible

Visibility; set to false to hide the element.

See the Components section for component-specific attributes and methods. The Customization section describes how to customize the look and feel of the components.

Using a Third-Party Component

You can also install and use other components in Fusion views. To do this, you first need to install the component npm package from the npm package registry using the pnpm package manager. For example, this command installs the latest version of the vanilla-colorful color picker and records the dependency in package.json:

npx pnpm add vanilla-colorful

After installation, the component is now ready to be imported and used in the Fusion view.

Note
If your project is configured to use the npm package manager instead of pnpm, use the command npm install vanilla-colorful --save.

The following example shows the hex triplet of the selected color in a Text Field:

import { html, LitElement } from 'lit';
import { customElement, query } from 'lit/decorators.js';

import '@vaadin/vaadin-text-field';
import { TextFieldElement } from '@vaadin/vaadin-text-field';

import 'vanilla-colorful';

@customElement('color-picker-view')
export class ColorPickerView extends LitElement {
  @query('#hex')
  hex!: TextFieldElement;

  render() {
    return html`
      <vaadin-text-field id="hex" label="HEX" readonly></vaadin-text-field>
      <hex-color-picker @color-changed="${this.colorChanged}"></hex-color-picker>
    `;
  }

  colorChanged(e: CustomEvent) {
    this.hex.value = e.detail.value;
  }
}