Hilla Documentation

Hilla Documentation

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’s 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 ComponentName. 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 property 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 most Vaadin components:

Property Description

disabled

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

title

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

hidden

Visibility; set this attribute to to hide the element.

See the Components section for component-specific attributes and methods. The Styling Components 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 type { 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;
  }
}