Using Components in Hilla
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:
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 |
---|---|
|
Whether the component is enabled; a disabled component cannot be interacted with. |
|
Additional label associated with the component, shown as a tooltip. |
|
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:
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;
}
}