Documentation

Documentation

Event Handling

Handling events in a Hilla application. Declarative event listeners and event objects in TypeScript.

Events are dispatched in the browser when the user interacts with the interface. Web applications can react to these interactions by handling events, for example running some code when the user clicks a certain button.

To handle events, applications register event listener methods for specific event types. Event types denote the type of interaction, such as click, on the interactive targets, typically interface elements.

Declarative Event Listeners

To register event listeners in Hilla application views, declare them in your Lit templates using @event bindings with view class methods. In the example below, the view registers an event listener for the sayHello() method to show the notification when the user clicks the button.

Open in a
new tab
@customElement('click-view')
export class ClickView extends LitElement {
  render() {
    return html`<vaadin-button @click="${this.sayHello}">Say hello</vaadin-button>`;
  }

  private sayHello() {
    Notification.show('Hello');
  }
}

You can also add event listeners programmatically when needed, as well as dispatch and listen for custom events. See the Lit Events documentation for these use cases, with examples.

Available Event Types

The most-often-used events in Hilla applications fall into two major categories: built-in and custom ones.

The built-in events, such as click, input, and change, are dispatched by the browser itself, and are typically available on every element. You can find comprehensive lists of the events available for all HTML elements in the Element API and the HTMLElement API references.

Web components, and hence Vaadin components, also dispatch custom events. See the API references for these in the Vaadin components documentation.

Event Object

The listener methods receive the event object as the first argument. The event objects provide some useful properties and methods, such as:

  • event.type: the event type string, for example click

  • event.target: a reference to the target (element) of the interaction

  • event.detail in CustomEvent types: often used by web components for event-specific data. For example, event.detail.value is frequently used to propagate the new value in property-changed events

  • event.preventDefault(): cancels the built-in handling of a particular event, for example to prevent the browser from navigating when the user clicks a link, after that click has been handled in the listener

In the example below, the event.detail.value is used in the value-changed event handler to extract the edited value property of the <vaadin-text-field> element:

Open in a
new tab
@customElement('value-changed-view')
export class ValueChangedView extends LitElement {
  @state()
  private name = '';

  render() {
    return html`
      <vaadin-text-field label="Your name" @value-changed="${this.nameChanged}"></vaadin-text-field>
      <div>Your name is: ${this.name}</div>
    `;
  }

  private nameChanged(event: CustomEvent) {
    this.name = event.detail.value;
  }
}

Some common use cases of event handling are also explained in other articles.

User Input in Forms

When creating forms in Hilla applications, consider using the Form Binder. With the form binder, you can avoid writing code to handle change events in the form, since the binder automatically tracks those changes.

View Properties

To maintain a consistent state within a view, it’s a good idea to use declarative template bindings (.property="${this.value}") and avoid the imperative element.property = this.value; code style in event listeners. See the Creating components for the binding syntax.

Application State

Developers often need to maintain the state consistent across the entire web application. To achieve this, consider using State Management.