Using Components in Hilla

Using Vaadin components and/or third-party web components in your Hilla views.

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

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

Using Components From Hilla

When bootstrapping a Hilla project with the CLI, all the 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/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 type-safe access to the component’s API. For example:

Open in a
new tab
import { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';

import '@vaadin/checkbox';
import '@vaadin/combo-box';
import type { ComboBoxValueChangedEvent } from '@vaadin/combo-box';

@customElement('greeting-view')
export class GreetingView extends LitElement {
  @state()
  private greetings = ['Hi', 'Hello', 'Dear'];

  @state()
  private allowCustomGreeting = false;

  @state()
  private greeting = 'Hi';

  render() {
    return html`
      <vaadin-combo-box
        label="Greeting"
        .items="${this.greetings}"
        .allowCustomValue="${this.allowCustomGreeting}"
        .value="${this.greeting}"
        @value-changed="${(e: ComboBoxValueChangedEvent) => (this.greeting = e.detail.value)}"
      ></vaadin-combo-box>
      <vaadin-checkbox
        @change="${this.checkboxChange}"
        label="Type Custom greeting"
      ></vaadin-checkbox>
    `;
  }

  checkboxChange(event: Event) {
    this.allowCustomGreeting = (event.target as HTMLInputElement).checked;
    if (!this.allowCustomGreeting) {
      this.greeting = this.greetings[0];
    }
  }
}

In the preceding example, the Combo Box and Checkbox components with the 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 code completion in the IDE.

HTML Attributes

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

Property Description

Property	Description
`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 it to `false` to hide the element.

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 it 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 Hilla 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 Hilla 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:

Open in a
new tab
import { html, LitElement } from 'lit';
import { customElement, query } from 'lit/decorators.js';

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

import 'vanilla-colorful';

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

  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;
  }
}

Hilla Documentation